{"id":51015319,"url":"https://github.com/cypher-asi/aura-storage","last_synced_at":"2026-06-21T09:30:41.485Z","repository":{"id":345608061,"uuid":"1185690762","full_name":"cypher-asi/aura-storage","owner":"cypher-asi","description":"The execution data layer for the AURA platform: specs, tasks, sessions, project agents, messages, logs","archived":false,"fork":false,"pushed_at":"2026-06-02T05:22:18.000Z","size":320,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T07:18:25.207Z","etag":null,"topics":["aura"],"latest_commit_sha":null,"homepage":"https://aura.ai","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cypher-asi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T21:07:09.000Z","updated_at":"2026-06-02T05:22:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cypher-asi/aura-storage","commit_stats":null,"previous_names":["cypher-asi/aura-storage"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cypher-asi/aura-storage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cypher-asi","download_url":"https://codeload.github.com/cypher-asi/aura-storage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypher-asi%2Faura-storage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34605335,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aura"],"created_at":"2026-06-21T09:30:40.889Z","updated_at":"2026-06-21T09:30:41.478Z","avatar_url":"https://github.com/cypher-asi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eaura-storage\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eThe execution data layer for autonomous agent workflows.\u003c/b\u003e\n\u003c/p\u003e\n\n## Overview\n\naura-storage stores all project execution data for the AURA platform — specs, tasks, sessions, events, project agents, log entries, processes (workflow definitions, runs, and artifacts), and private observability history. All AURA clients (desktop, web, mobile) and aura-swarm (cloud agent orchestration) connect to this service for execution state.\n\nProjects themselves live in [aura-network](https://github.com/cypher-asi/aura-network) (the social layer). This service references project UUIDs from there. Together: aura-network owns \"what exists\", aura-storage owns \"what happened\".\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Rust 1.85+\n- PostgreSQL 15+\n\n### Setup\n\n```\ncp .env.example .env\n# Edit .env with your database URL and auth config\n\ncargo run -p aura-storage-server\n```\n\nThe server starts on `http://0.0.0.0:3000` by default. Migrations run automatically on startup.\n\n### Health Check\n\n```\ncurl http://localhost:3000/health\n```\n\nReturns:\n```json\n{\"status\": \"ok\", \"timestamp\": \"2026-03-18T22:00:00Z\"}\n```\n\n### Environment Variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `DATABASE_URL` | Yes | PostgreSQL connection string |\n| `AUTH0_DOMAIN` | Yes | Auth0 domain for JWKS |\n| `AUTH0_AUDIENCE` | Yes | Auth0 audience identifier |\n| `AUTH_COOKIE_SECRET` | Yes | Shared secret for HS256 token validation (same as aura-network) |\n| `INTERNAL_SERVICE_TOKEN` | Yes | Token for service-to-service auth (aura-swarm -\u003e aura-storage) |\n| `PORT` | No | Server port (default: 3000) |\n| `AURA_NETWORK_URL` | No | aura-network base URL for org membership checks and cost data in stats |\n| `AURA_NETWORK_TOKEN` | No | Internal service token for aura-network |\n| `CORS_ORIGINS` | No | Comma-separated allowed origins. Omit for permissive (dev mode) |\n| `RUST_LOG` | No | Tracing filter (default: `aura_storage=debug,tower_http=debug,info`) |\n\n---\n\n## Authentication\n\nAll API endpoints require a JWT in the `Authorization: Bearer \u003ctoken\u003e` header. Tokens are obtained by logging in via zOS API. Same tokens as aura-network — both RS256 (Auth0 JWKS) and HS256 (shared secret) are accepted.\n\nInternal (service-to-service) endpoints use `X-Internal-Token` header instead.\n\nUnlike aura-network, this service does **not** auto-create users. The `created_by` field stores the user's UUID from the JWT but does not validate it against a users table — that lives in aura-network.\n\n---\n\n## Processes\n\nProcesses are visual workflow definitions built as directed node graphs. Each process contains:\n\n- **Nodes** — individual steps in the workflow. Types include `ignition` (entry point / trigger), `action` (agent-executed task), `condition` (branching logic), `prompt` (LLM prompt), `artifact` (output generation), `delay`, `merge`, `sub_process`, and `for_each`.\n- **Connections** — edges linking nodes together, defining execution order. Each connection has a source and target node with optional handles for multi-output branching.\n- **Runs** — each execution of a process creates a run, tracking status (`pending` → `running` → `completed`/`failed`/`cancelled`), trigger type (`manual` or `scheduled`), token usage, and cost.\n- **Events** — per-node execution records within a run. Each event captures the node's input, output, status, token usage, and model used.\n- **Artifacts** — outputs produced during a run (reports, documents, data files, media, code). Metadata is stored here; file content remains on the local machine.\n- **Folders** — optional grouping for organizing processes within an organization.\n\nProcesses are scoped to an organization and optionally linked to a project. They can be scheduled via cron expressions for automatic execution, or triggered manually. Sub-processes are supported via `parent_run_id` on runs.\n\nThe desktop client (aura-code) can operate in two modes: local-only (RocksDB) when `AURA_STORAGE_URL` is not set, or proxied to aura-storage for cross-team sharing when configured.\n\n## API Reference\n\nSee [docs/api.md](docs/api.md) for the full API reference.\n\n---\n\n## Integration Guide\n\n### From aura-code (Desktop)\n\n```\nAuth:       zOS API (login) -\u003e gets JWT\nNetwork:    aura-network (profiles, orgs, agents, feed, projects)\nStorage:    aura-storage (specs, tasks, sessions, events, project agents, logs, processes)\nBilling:    zero-payments-server (credit balance, debit via JWT)\nLocal:      RocksDB (terminal, filesystem, settings)\n```\n\nOn app load: fetch projects from aura-network, then fetch execution data from aura-storage for active projects.\n\n### From aura-swarm (Cloud Agents)\n\n```\n1. Update agent status:    POST /internal/project-agents/:id/status\n2. Create session:         POST /internal/sessions\n3. Write events:           POST /internal/events (per LLM call)\n4. Write logs:             POST /internal/logs\n5. Post to feed:            POST aura-network /internal/posts\n```\n\nUse `X-Internal-Token` for aura-storage internal endpoints. Use the user's JWT for aura-network activity posts and credit debits.\n\nPublic `/api/processes` and `/api/process-folders` endpoints validate org membership through Aura Network before returning or mutating org-scoped data. Desktop-triggered process run, event, and artifact writes now use JWT-backed public process routes; the internal `/internal/process-*` endpoints remain available for service-to-service executor flows.\n\n### From AURA Observability\n\n```\n1. Run live eval probes:         aura-os status:probes\n2. Build latest public status:   aura-os status:snapshot\n3. Persist private history:      POST /internal/observability/runs\n```\n\nThe public `/observability` page keeps reading the latest static status JSON.\nAura storage keeps the private history used to answer internal questions like\n\"which eval flakes most often?\" and \"when did this check get slower?\".\n\n### From Mobile\n\nSame API as desktop — all endpoints are API-first. Authenticate via zOS, then call aura-storage directly.\n\n---\n\n## Architecture\n\n| Crate | Description |\n|---|---|\n| **aura-storage-core** | Shared types, error handling, pagination |\n| **aura-storage-db** | PostgreSQL connection pool and migrations |\n| **aura-storage-auth** | JWT validation (Auth0 JWKS + HS256) and auth extractors |\n| **aura-storage-server** | Axum HTTP server, router, handlers, WebSocket |\n| **aura-storage-project-agents** | Project agent assignment and status tracking |\n| **aura-storage-specs** | Spec management (requirements documents) |\n| **aura-storage-tasks** | Task management with status state machine |\n| **aura-storage-sessions** | Agent execution sessions |\n| **aura-storage-events** | Session events (typed event stream) |\n| **aura-storage-logs** | Structured log entries |\n| **aura-storage-processes** | Process workflows, nodes, connections, runs, events, and artifacts |\n| **aura-storage-observability** | Private eval/status history for internal trend analysis |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypher-asi%2Faura-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypher-asi%2Faura-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypher-asi%2Faura-storage/lists"}