# AOS, an agent workspace you run from source because no binary is published

> AOS is a Rust control plane plus React UI for agent sessions that must survive a disconnect, with NL2SQL datasources, a Bot Gateway and Skills. The repository ships no release archive, so every deployment starts from the source tree.

**programming-pupil/aos** — A source-first Agent Operating System for recoverable conversations, deep research, NL2SQL, mobile Bot Gateway, Skills/MCP, and progressive engineering design.

- Repository: https://github.com/programming-pupil/aos
- Stars: 38 · Forks: 2
- Language: Rust
- License: NOASSERTION
- Published: 2026-08-26 · Updated: 2026-08-26 · Language: en
- Canonical page: https://hysenlabs.com/projects/programming-pupil-aos

## SQLite holds the control plane, business data stays outside

The architecture in the README is one Rust WebServer with four things hanging off it: the agent runtime and its recoverable sessions, model providers and optional web-search extensions, datasources, and repository adapters for Skills and MCP. Everything a user touches arrives through a Web UI or an external Bot.

That server owns one SQLite database, and the README is explicit that this database belongs to the AOS control plane rather than to the customer's data. Business databases are configured as external NL2SQL datasources, and they are not required to boot AOS. The practical consequence is a clean separation: a workspace can come up with no customer database attached and have NL2SQL added later as a datasource. The second constraint is sharper. A single AOS process owns one local data directory, so the platform is not designed to be scaled horizontally by pointing several servers at shared storage.

## generate-env.sh exists because Docker Compose will not start without three secrets

The shortest supported contributor path is two commands, and the first one writes a `.env` file that the second one depends on:

```bash
./scripts/generate-env.sh
docker compose up --build
```

After the build, opening http://localhost:3000 starts setup. Asking the model to do provider-backed work needs one more step: an enabled chat-scoped API key added under System, then API Keys, since the runtime expects credentials configured there rather than baked into a shell. For native development the same split exists as `./scripts/setup-environment.sh --check` followed by `./scripts/aos-start.sh`.

The compose file treats three variables as hard requirements, marked with the `:?` form so the stack aborts when any of them is empty:

```bash
JWT_SECRET=
ENCRYPTION_KEY=
TOKEN_ENCRYPTION_KEY=
```

The example environment explains what each one is for. `JWT_SECRET` can be any strong random string. `ENCRYPTION_KEY` must be exactly 32 bytes, because API keys are AES-256-GCM encrypted. `TOKEN_ENCRYPTION_KEY` belongs to the current Git project token store.

## /data/aos.db is created automatically and wants a local filesystem

The platform database appears without a migration step: AOS creates `/data/aos.db` on its own. What it will not tolerate is a shared network filesystem, and the example environment says so in plain terms. Keep the data directory on a local filesystem, and run only one AOS server process against it. That single line rules out the usual answer to scaling questions, and it pairs with the connection settings the compose file exposes.

Four SQLite knobs are configurable, and their defaults matter when you tune them. `AOS_SQLITE_MAX_CONNECTIONS` and `AOS_SQLITE_CONTROL_MAX_CONNECTIONS` both default to 8, `AOS_SQLITE_BUSY_TIMEOUT_MS` to 30000 and `AOS_SQLITE_ACQUIRE_TIMEOUT_SECS` to 30. Two separate pools, one for control-plane work and one for the rest, each sized independently, and both waiting on SQLite locks rather than returning an error immediately. Uploads have their own ceiling: `UPLOAD_MAX_FILE_BYTES` defaults to 52428800 and `UPLOAD_MAX_IMAGE_BYTES` to 1048576, so the image path is two orders of magnitude tighter than the general file path.

## Provider adapters sit behind a fallback path that stays on by default

Search providers and MCP servers are optional extensions, and the configuration boundary that matters most to an operator is this: the built-in fallback path remains the default when an enhancement is not configured. A deployment that forgets to wire a search provider still answers, it just answers with less.

Model credentials are stored per tenant through the API Keys surface and are never committed to the repository. The compose file carries the shape of that wiring as defaults: `DEFAULT_MODEL` falls back to `anthropic/claude-opus-4-8`, with `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` both defaulting to empty, plus `EMBEDDING_MODEL` and `EMBEDDING_BASE_URL` for retrieval and `AOSD_GITHUB_TOKEN` for the repository adapters. The README is careful about what it promises here, saying it does not claim that every provider adapter or every workflow is production-ready on every platform yet, and that tenant permissions, provider support, network access and feature maturity are shown explicitly in the linked documentation.

## Skills are treated as untrusted input, and reconnect recovery is local

Skills, the optional extension mechanism, get the most cautious treatment in the configuration boundaries: they are treated as untrusted input during installation and are subject to safety checks and permission boundaries. Install one and you are running someone else's instructions inside an agent that can call your tools.

Recoverability has a narrower scope than the name suggests. Long-running tasks persist state and events so a client reconnect can recover context, which means the browser can come back and pick up the thread. Delivery to external chat platforms is a separate story: that still depends on each platform's own API policy, and the Bot Gateway polls inbound on `BOT_GATEWAY_INBOUND_POLL_SECS`, defaulting to 10. Concurrency is capped rather than open ended, with `PM_RESEARCH_TASK_MAX_CONCURRENT` at 4 and `PM_RESEARCH_TASK_MAX_CONCURRENT_PER_TENANT` at 2, so one tenant cannot consume the whole research budget of a shared deployment.

## Development checks span two trees, cargo and npm

The Rust workspace and the React front end are checked separately, and the sequence is fixed enough to be worth copying:

```bash
cd rust
cargo fmt --all
cargo check -p web-server
cargo test --workspace --all-features
```

Then the front end gets its own install and build gates:

```bash
cd ../webui
npm ci
npm run typecheck
npm run build:ci
```

`webui/` is a React and Vite application, `rust/` holds the workspace, the API, the runtime, the agent orchestration and the WebServer, and the targeted test guides cover the Bot Gateway, data attribution, NL2SQL configuration and the progressive engineering design workflow. `eval/` and `examples/` carry deterministic fixtures and small integration examples, with `examples/bot-router/` and `examples/code-studio/` as the visible pieces and a `demo_manifest.json` tying them together.

## No archive in the repository, and AOS Offline is built separately

There are no GitHub releases on this repository, and that is a decision rather than an omission. The README states that AOS is an active source release under regression testing, that the repository holds the source tree, documentation, tests and packaging scripts, and that prebuilt AOS Offline archives are intentionally kept out of Git history. They get attached to GitHub Releases only when a build is ready.

What AOS Offline is, once it exists: a separately built distribution for macOS, Linux and Windows x64. Maintainers build and validate an archive, then publish it with its checksum and upgrade notes, and until that happens the source workflow is the only path. The packaging scaffolding is in the tree: a Containerfile whose compose service targets `server-runtime`, a `docker/` directory, `install.sh`, and `scripts/` holding setup, start and stop, upgrade and packaging helpers, with `OPEN_SOURCE_RELEASE_CHECKLIST.md` recording the process. Expect to do this build yourself.

## Half the operational documentation ships in Chinese filenames

The documentation set is large and the language split is visible in the filenames. English entries include `docs/ARCHITECTURE.md`, `docs/MODEL_CAPABILITY_PROFILES.md`, `docs/AGENTOPS_WATCHDOG_DESIGN.md`, `docs/BOT_CAPABILITY_CONTRACT.md`, `docs/BOT_GATEWAY_ENTERPRISE.md` and `docs/DESIGN_DATASOURCES_NL2SQL.md`. Their Chinese counterparts are the deployment guide, the complete test guide, the engineering design center, the release checklist, plus `CONTRIBUTING`, `CODE_OF_CONDUCT` and `SECURITY` variants, and a second `README.zh-CN.md` at the root.

Three files sit outside the docs directory and are worth knowing about. `USAGE.md` and `PHILOSOPHY.md` are top-level, and `docs/READABILITY_SPEC.md` is a readability specification, which suggests the project treats the inspection surface as something to specify. A Node version badge in the README asks for `=20.19 or >=22.12`, which is the constraint the web front end is tested against. Licensing is Apache License 2.0, with third-party and upstream attribution notices collected in `NOTICE.md`. The last push landed on 2026-09-27.

## Conclusion

AOS fits a team that wants agent runs to be resumable and inspectable, and that is willing to build from source, supply its own model credentials and keep its business databases outside the platform. It does not fit anyone expecting a downloadable install or a finished adapter for every chat platform. Before committing, run ./scripts/generate-env.sh and docker compose up --build on a scratch host, then check whether the third-party data sources you care about are reachable from your network.

## FAQ

### What does AOS stand for in software?

In this project AOS means Agent Operating System: a Web-first, multi-tenant workspace for building agent workflows around one recoverable session, bringing conversation, research, memory, files, Skills, MCP and external Bot channels into one surface.

### How do I start AOS from the source tree?

Run ./scripts/generate-env.sh and then docker compose up --build, open http://localhost:3000 and complete setup, then add an enabled chat-scoped API key under System and API Keys before asking the model to do provider-backed work.

### Which secrets does AOS require before Docker Compose starts?

JWT_SECRET, ENCRYPTION_KEY and TOKEN_ENCRYPTION_KEY, each marked required in docker-compose.yml. ENCRYPTION_KEY must be exactly 32 bytes because API keys are AES-256-GCM encrypted, JWT_SECRET can be any strong random string, and TOKEN_ENCRYPTION_KEY is used by the current Git project token store.

### Does AOS ship a downloadable binary?

No. The repository has no GitHub releases and release archives are deliberately not committed to it. AOS Offline is a separately built distribution for macOS, Linux and Windows x64 that maintainers publish under GitHub Releases with a checksum and upgrade notes once a build is ready.

### Can AOS query my business database?

Yes, as an external NL2SQL datasource configured with attribution workflows and semantic retrieval. Those datasources are not needed to boot AOS, because the platform database is SQLite and belongs to the control plane, and AOS creates /data/aos.db automatically.

## Sources

- [Official README](https://github.com/programming-pupil/aos#readme)
- [Project repository](https://github.com/programming-pupil/aos)
- [README](https://github.com/programming-pupil/aos/blob/main/README.md)
- [Releases](https://github.com/programming-pupil/aos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/programming-pupil-aos