MaxOS Spec

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.

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:

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.

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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: max-now
• Source: max-now/MaxOS-Spec
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.