repository·main·Indexed 41 days ago
https://github.com/aura-industry/auraosAn open-source software suite providing AI agents with real-world operational tools, including AuraWallet, a secure secret manager for passwords, API keys, and credit cards. It features human-approval flows, scoped tokens, and integration via the Model Context Protocol (MCP) and specialized agent skills.
AuraMaxx runs as a suite of local processes. Data is stored locally in ~/.auramaxx/ (SQLite database, encrypted agent files, and config).
| Process | Port | Purpose |
|---|---|---|
| Express (Wallet API) | :4242 | Core API handling auth, wallets, credentials, and transactions. |
| Dashboard | :4747 | Web UI for human approvals, wallet management, and monitoring. |
| WebSocket | :4748 | Real-time event broadcasting for the Dashboard. |
| Cron | N/A | Background jobs for balance syncing and price updates. |
| MCP Server | N/A (stdio) | Tool interface for AI agents like Claude or Cursor via stdio transport. |
Key Security Property: The SIGNING_KEY used for auth is stored only in memory. If the server restarts, the key is wiped, all existing tokens become invalid, and agents must re-authenticate. This ensures that a stolen database alone is insufficient to forge valid tokens.
Every authentication request requires a human gate. When an agent requests access, it receives an approveUrl (e.g., http://localhost:4747/approve/<reqId>).
For Agents: Always provide the direct approveUrl to the human user so they can review the action summary, requested permissions, risk level, and spending limits, and then click Approve or Deny.
Choose the appropriate authentication flow based on your use case:
POST /auth). It is bound by profile defaults and allows for tightening overrides.POST /auth with action field). This allows a single approval to trigger a specific command.POST /actions/token). This is for headless tools requiring admin-controlled issuance.POST /auth/validate) to detect expiration before a call fails.POST /actions/tokens/revoke) to immediately disable a compromised token.The wallet and app UI flows utilize several common event channels via WebSockets to provide real-time updates. Developers should listen for these specific event types to synchronize UI state with wallet operations:
asset:changed: Triggered when asset balances or metadata change.tx:created: Triggered when a new transaction is initialized.action:created: Triggered when a new action is generated.action:resolved: Triggered when an action reaches a resolution state.action:executed: Triggered when an action has been successfully executed.For HTTP snapshots of the current state, use the /logs and /dashboard endpoints.
Tokens are issued based on predefined profiles. You can use profileOverrides to further restrict a profile, but overrides are tighten-only (they can only reduce privileges, never increase them).
strict: Minimal permissions (secret:read), 15 min TTL, max 50 reads. Excludes sensitive fields like password and seedPhrase.dev: Broader permissions for development, 1 hour TTL, max 500 reads.admin: Full access, 1 hour TTL, unlimited reads.ttlSeconds: Must be shorter than profile default.maxReads: Must be $\le$ profile default.scope, readScopes, writeScopes: Must be a subset of the profile's scopes.excludeFields: Can only add more exclusions.# Example: Requesting a 'dev' profile but tightening it further
curl -sS -X POST http://localhost:4242/auth \
-H "Content-Type: application/json" \
-d '{
"agentId": "my-agent",
"profile": "dev",
"pubkey": "'$PUBKEY_B64'",
"profileOverrides": {
"ttlSeconds": 600,
"readScopes": ["agent:agent"],
"writeScopes": ["agent:agent"],
"excludeFields": ["cvv", "seedPhrase", "privateKey", "refresh_token", "password"]
}
}'AuraWallet uses a multi-layered security model designed to keep secrets local and under human control:
strict, dev, or admin.AuraOS tokens use a canonical payload shape to define an agent's capabilities, including permissions, financial limits, and credential access.
Key fields include:
agentId: Unique identifier for the agent.permissions: Array of permission strings (e.g., secret:read).limits: Object containing financial constraints for fund, send, swap, and launch.walletAccess: Array of specific wallet addresses the token is authorized to use.credentialAccess: Configuration for accessing secrets, including read/write scopes, excludeFields for redaction, ttl (time-to-live), and maxReads limits.exp/iat: Issuer-managed timestamps for expiration and issuance.Note: limit is a legacy field; use limits.fund for canonical budget enforcement.
{
"agentId": "string",
"permissions": ["secret:read"],
"exp": 1735689600000,
"iat": 1735686000000,
"limits": {
"fund": 0,
"send": 0,
"swap": 0,
"launch": 0
},
"walletAccess": ["0x..."],
"credentialAccess": {
"read": ["agent:primary"],
"write": ["agent:primary"],
"excludeFields": ["cvv", "password"],
"ttl": 3600,
"maxReads": 500
},
"agentPubkey": "PEM-or-base64",
"limit": 0
}AuraMaxx implements a strict access model for credentials. Permissions are managed via scopes and can be restricted to specific agents, tags, or IDs.
secret:read: Allows listing metadata and reading encrypted fields.secret:write: Allows creating, updating, and deleting credentials.credentialAccess.read or credentialAccess.write to restrict access to specific agents, tags, or credential IDs.excludeFields to strip sensitive fields before the response is encrypted.ttl (Time To Live) and maxReads to enforce governance limits on credential access.Credential read endpoints return data encrypted to the caller's agentPubkey using RSA-OAEP or a hybrid RSA+AES-GCM approach for larger payloads.
AuraMaxx uses different flows depending on the user type and use case:
POST /auth): The standard flow for agents. It is profile-based and requires human approval. Use this for ongoing access.POST /auth with action field): A one-off escalation where a specific action is pre-computed and auto-executes immediately upon human approval.POST /actions/token): An admin-only flow for headless orchestration or trusted automation. It can use either profile mode or permissions mode, but not both.POST /unlock): Used for local machine setup and human admin sessions.AuraMaxx provides scoped access to credentials using a three-part mental model for defining what an agent can do:
agent:agent, agent:*, tag:<label>, cred-xxxxx, or * (wildcard).secret:read, secret:write, totp:read.maxReads, ttl, and per-credential rate limits.Additionally, Field Minimization (excludeFields) can be used to strip sensitive data from a credential before it is encrypted and sent to the agent.
When developing installed apps for AuraOS, use the injected CSS variables to ensure your app automatically adapts to light/dark mode and accent color changes. The host injects these variables into every app iframe.
--color-accent: Primary accent color (default: #ccff00)--color-background: Page background--color-background-alt: Alternate background (e.g., sidebar)--color-surface: Card/app background--color-surface-alt: Alternate surface--color-text: Primary text--color-text-muted: Secondary text--color-text-faint: Tertiary/disabled text--color-border: Default border--color-border-muted: Subtle border--color-border-focus: Focus ring--color-warning: Warning state (#ff4d00)--color-danger: Error/danger state (#ef4444)--color-success: Success state (#00c853)--color-info: Info state (#0047ff)Use {color} where color is blue, orange, lime, purple, gray, teal, or rose:
--app-{color}-band: App header band color--app-{color}-accent: App border accent--app-{color}-bg: App background tint--app-{color}-text: App text color<style>
body {
background: var(--color-surface, #fff);
color: var(--color-text, #0a0a0a);
border: 1px solid var(--color-border, #d4d4d8);
}
.highlight {
color: var(--color-accent, #ccff00);
}
</style>