Skip to content
Ony docs

Quickstart

This is the Lite path: a full Ony.ai server running on SQLite, with no Docker, Postgres, or Redis. You will install Ony.ai, start the server, create an account, wire your agent, and set a mode. It takes a couple of minutes.

  1. Install Ony.ai.

    Terminal window
    pip install ony

  2. Start the local server.

    Terminal window
    ony up
    #   Ony is running at http://127.0.0.1:8001  (dashboard + API)

    This creates a SQLite database under your Ony.ai home directory and serves the dashboard and API together. Leave it running.

  3. Create your account.

    Open http://127.0.0.1:8001 in your browser and sign up. This is the first user on your own server, so it becomes the owner.

  4. Wire your agent.

    From your project directory:

    Terminal window
    ony init

    ony init enrolls this machine as a device (if it is not already), then installs the /ony skill, the gate hook, and the lifecycle hooks into the project’s .claude/. Restart your Claude Code session (or run /reload-plugins) so the /ony command loads - Claude Code discovers project skills at startup.

  5. Choose a mode.

    Inside Claude Code, or from any terminal in the project:

    Terminal window
    ony away    # phone me for every step Claude would stop on (remote control)
    # or
    ony on      # phone me only for high-risk actions

    That is the whole loop. When the agent hits a step that needs you, Ony.ai raises a handoff, you decide, and the agent keeps going. See the /ony modes for the full set.

The calls are simulated until you add a carrier

Section titled “The calls are simulated until you add a carrier”

Out of the box ony up uses a built-in mock carrier, so no phone actually rings yet. Handoffs surface in the dashboard, where you approve or deny them. The Overview page’s “Simulate a handoff” button walks the whole flow end to end with no agent and no phone at all, so you can see the loop before you connect anything real.

Real calls start once you add a telephony provider (SignalWire, Twilio, Telnyx, or Plivo) under Integrations -> Telephony in the dashboard and verify your number. So you can try the loop first, then flip on real calls. See the carriers guide.

Verify the wiring

Section titled “Verify the wiring”
Terminal window
ony status    # enrollment, connectivity, and the current mode
ony doctor    # one actionable line per check across the whole install

Next steps

Section titled “Next steps”
  • How the gate works - when Ony.ai rings and when it stays silent.
  • The /ony modes - off, on, away, and project scope.
  • Self-hosting - the Docker all-in-one stack (Postgres, Valkey, one origin) for a team or a public host, plus telephony and production config.