Content
# MaxOS
MaxOS is a specification for operating AI agents as persistent worker identities
inside organizations. Every AI Employee has a human owner, bounded authority,
scoped capabilities, durable context, and an auditable execution history.
## Architecture at a Glance
MaxOS separates organizational work into three layers:
- the **Foundation** mediates Skills, Connections, Memory, Triggers, models, and
execution environments through MaxOS MCP;
- **Virtual Employees** bind stable identity, a Human Owner, a narrow role,
authority, and context; and
- **Autopilot** coordinates bounded handoffs between employees and humans through
visible state in systems such as Linear or Slack.
Hosted sandbox agents and locally operated agents use the same scoped capability
plane. Changing the runtime must not change what an employee is authorized to
read, remember, or do.
MaxOS treats the Harness, LLM, and execution environment as independent choices.
The Harness controls context, the agent loop, and Tool use; the LLM supplies
model inference; and the execution environment runs the Harness and per-Run
Sandbox locally, in a hosted cloud, or across a hybrid deployment. A deployment
can replace any of these without changing the employee's identity, authority,
Skills, memory scope, or audit obligations.
## Read and Implement the Specification
[SPEC.md](SPEC.md) is the normative MaxOS contract. It defines a compact core and
separately declared governance profiles. A core implementation does not need to
claim ownership transfer, high-impact approval, open-ended execution,
delegation, privacy lifecycle, incident response, or formal assurance.
The specification is independent of programming language, model provider,
database, cloud, and user interface. To implement it, give [SPEC.md](SPEC.md) to
your engineering team or coding agent together with the deployment constraints
for your environment.
## Run the Self-Contained Reference
The Joke Competition is a narrow executable example of the specification. It
uses one workflow, three Virtual Employees, a human review gate, scoped memory,
and a governed learning loop. Its deterministic mode needs Node.js 22.18 or
later and does not contact an external account or use a real credential.
```console
npm ci --ignore-scripts
npm run demo
npm run check
```
The local workspace can run the employees through Codex App Server. Install
Codex, or use the binary bundled with the Codex or ChatGPT desktop app, and
authenticate it before launch:
```console
codex login
npm run start:local
```
`start:local` opens the workspace, executes each employee handoff, and pauses at
the simulated human review gate. The interface identifies its in-memory Linear
source, deterministic joke generator, Codex employee model, and simulated
connection rather than presenting them as live external services.
## Connect the Linear Autopilot
Use a dedicated Linear workspace unless creating real test resources in an
existing workspace is acceptable. The supplied Linear key must be able to create
a team, project, workflow states, issues, and comments.
```console
export LINEAR_API_KEY=lin_api_...
export OPENAI_API_KEY=sk-...
# Authenticate Codex separately when OPENAI_API_KEY is not used by Codex.
codex login
npm run setup
npm run create -- "Airport humor championship"
npm start
```
Setup creates or reuses the `MaxOS Demo` team, the `Joke Competition` project,
and the `Player A Turn`, `Player B Turn`, `Judge`, `Human Review`, and `Result`
states. The supervisor polls Linear every five seconds, assigns each eligible
state to its employee, and runs that employee through Codex App Server and the
scoped MaxOS MCP server. The workspace remains available at
`http://127.0.0.1:4310`.
When an issue reaches `Human Review`, a person confirms Player A or Player B in a
Linear comment. The Judge then resumes, records the score in its memory, and
moves the issue to `Result`.
## Reference Scope and Project Status
[reference/README.md](reference/README.md) maps the executable behavior to stable
specification requirements and documents credential boundaries, memory,
external integration, and known limitations.
The reference covers one evaluation-scale slice: one Trigger, one connection,
two Skills, three employees, scoped memory, and a human-governed learning loop.
It does not implement the hosted browser-chat Sandbox or represent the complete
MaxOS product.
> **Engineering preview:** MaxOS 0.1.0-draft is intended for testing in trusted
> environments. Neither the specification nor the reference is a production
> runtime, certification program, or legal-compliance framework.
## Acknowledgements
OpenAI Symphony influenced the initial public spec-and-reference presentation of
MaxOS. MaxOS has its own architecture, requirements, and reference behavior. See
[NOTICE](NOTICE) for attribution.
MaxOS is not affiliated with or endorsed by OpenAI.
## License
This project is licensed under the [Apache License 2.0](LICENSE). See
[NOTICE](NOTICE) for attribution.
MCP Store