GitHub
Back to AgentOS

Built in the open. Run it yourself.

AgentOS is small, open source and MIT. Build it from source, see how the parts fit together, and reach your computer from anywhere with your own relay.

Run it from source.

Rather build it yourself? You need a Mac, Node.js 20.19 or later, and pnpm 10.

  1. 1 Get the code and build it 

    git clone https://github.com/Synapsr/AgentOS.git
cd AgentOS
pnpm install
pnpm build

  2. 2 Wake the agent, with no key yet 

    AGENTOS_ENGINE=mock pnpm start

    A practice brain: no key, no cost, everything else real. It prints the address where you finish setting up.

  3. 3 Give it a real brain 

    pnpm start

    Runs agentos start, the core alone. Paste an Anthropic API key during setup, or later in Settings.

  4. 4 Add your phone 

    pnpm agentos pair

    Shows a one-time QR code.

  5. From a terminal pnpm agentos say "…" Also status, pair and url.

    The desktop app pnpm desktop Tauri 2, so you need Rust.

    The iPhone app cd apps/ios && xcodegen Then open the project in Xcode.

Everything is a plain file.

No database. What Nova knows lives in ~/.agentos, readable with any editor.

  • ~/.agentos/
  • config.json who the agent is, how much it asks
  • secrets.json API keys, readable only by you
  • devices.json paired devices, token hashes only
  • events.jsonl everything that happened
  • threads/ one file per conversation
  • files/ screenshots and other files

One small protocol.

HTTP and WebSocket, in JSON, defined in packages/protocol. Every client speaks it: the apps, the web client, your scripts.

Three parts. Each one replaceable.

AgentOS is small on purpose. The core runs on your computer and keeps the conversation, the requests and the safety rules. Everything else plugs into it.

You

  • iPhone
  • Earbuds
  • Browser
  • Apple Watch, in progress

One small, documented protocol

Your computer

The AgentOS core: conversations, requests, safety rules, plain files.

  • The brain

    Claude, through the Claude Agent SDK. The engine is an interface, so other models can plug in.

    • Claude
    • Your model, same interface

  • Eyes and hands

    Your operating system’s accessibility tree, through the open-source agent-desktop. Nova reads what is on screen and acts on it: buttons, fields, menus.

    • agent-desktop

  • Ears and mouth

    Speech on your phone by default, with no key. Add one key for a premium voice such as ElevenLabs, or point it at your own open-source speech server.

    • Your phone
    • ElevenLabs
    • Your own server

Reach your computer from anywhere, your way.

Your phone and your computer talk to each other directly. Pick whichever of the three suits you.

  1. On the same network

    At home or at work, your phone finds your computer by itself, and the connection is encrypted with your computer’s own certificate.

  2. Anywhere, with Tailscale

    Install Tailscale on both. AgentOS notices and puts that address in the pairing code. Tailscale encrypts the connection, and there is no server to run.

  3. Anywhere, with your own relay

    Run one small container on a server you own. It is private: it only accepts computers that present its token. Your computer connects out to it, so nothing opens on your home network.

Your own relay. There is no published image yet, so you build it from your clone; one will come with the first release.

docker build -f packages/relay/Dockerfile -t agentos-relay .

RELAY_TOKEN=$(openssl rand -hex 32)
echo "$RELAY_TOKEN"     # your computer will need it
docker run -d -p 8080:8080 -v agentos-relay:/data -e RELAY_TOKEN="$RELAY_TOKEN" agentos-relay

Then give your computer the relay’s address and its token, in Settings › Advanced. Whoever runs a relay can read what passes through it, so run your own. End-to-end encryption between phone and computer is planned.

More than one computer?

Pair each one. Your phone shows them together, each with its own agent.

With each agent, one conversation on top, and as many background jobs as it needs underneath.

  • Nova Studio Mac · Running the tests
  • Iris MacBook Air · Nothing to do
  • Atlas Office Mac mini · Can’t reach your computer