Orchestratia

Getting Started

Get Orchestratia up and running in under 10 minutes. This guide walks you through creating your account, connecting your first server, and assigning your first task to an AI coding agent.

1. Create Your Account

  1. Go to orchestratia.com/signup
  2. Sign up with email or use Google / GitHub OAuth
  3. Verify your email address (check your inbox for a verification link)
  4. You're in — you'll land on the dashboard

2. Create a Project

Projects are workspaces that group your servers, sessions, and tasks together. Team members are invited per-project.

  1. Click Projects in the sidebar
  2. Click + New Project
  3. Enter a name (e.g., "My App" or "Backend Services")
  4. Click Create Project

Your project is now ready. You can configure settings like plan approval requirements later.

3. Register Your First Server

To connect a server where AI agents will run, you need to install the agent daemon.

Generate a Registration Token

  1. Go to Servers in the sidebar
  2. Click + Add Server
  3. Set a label and expiry time
  4. Copy the install command

Install the Agent Daemon

The install command differs per OS. The dashboard generates the right one for you when you create the token.

Linux (Ubuntu/Debian/RHEL/Arch):

curl -fsSL https://install.orchestratia.com/linux | sudo bash -s -- TOKEN

macOS (via Homebrew):

brew install orchestratiahq/tap/orchestratia-agent && \
orchestratia-agent --register TOKEN

Windows (PowerShell):

$env:ORC_TOKEN='TOKEN'; irm https://install.orchestratia.com/windows | iex

Each installer registers with your hub, sets up the daemon to run at boot (systemd/launchd/scheduled task), and starts it. Your server appears on the dashboard as Online within seconds.

Verify the Connection

Go to Servers — you should see your server with a green status indicator and system stats (CPU, memory, disk).

4. Start a Session

Sessions are live terminal connections to your servers where AI agents do their work.

  1. Go to your Project (click the project name)
  2. Click the + tile to start a new session
  3. Select your server and choose a working directory
  4. The terminal opens — you're now looking at a live PTY on your remote server

You can type commands, resize the terminal, and watch output in real time.

5. Create and Assign a Task

Tasks are work items that you assign to AI agents.

  1. Go to Tasks in the sidebar
  2. Click + New Task
  3. Fill in:
    • Title: What the agent should do (e.g., "Add login page")
    • Spec: Detailed description of the work
    • Priority: Critical, High, Normal, or Low
    • Project: Select your project
  4. Click Create Task
  5. Open the task and click Assign — choose your session

The task is now assigned. If an AI agent (Claude Code, Gemini CLI, etc.) is running in that session, it will receive the task automatically and begin working.

6. Watch the Agent Work

Once a task is assigned and an agent is running:

  1. Open the Terminal for the project — you'll see the agent's live output
  2. The task status moves through: Pending → Assigned → Running → Done
  3. If the agent needs help, it will request an Intervention — you'll see it in the Interventions queue
  4. Respond to interventions from the dashboard, and the response is injected directly into the agent's session

What's Next?

Now that you have the basics, explore these capabilities:

  • Task Dependencies — Chain tasks so downstream work starts automatically when upstream completes
  • Plan Mode — Require agents to submit plans for approval before they start coding
  • Session Sharing — Share live terminals with teammates for pair debugging
  • Telegram Notifications — Get mobile alerts when agents need attention
  • Approval Rules — Control which tools agents can use across your fleet
  • AI Agent Guide — Complete CLI reference for AI agents using the orchestratia command

Uninstalling the Agent

If you need to remove the agent from a server, run the matching one-liner. The uninstaller stops the daemon, removes the service/scheduled task, cleans PATH entries, and deletes config + logs.

Linux

curl -fsSL https://install.orchestratia.com/uninstall-linux | bash

Or, for a non-interactive run (no confirmation prompt):

curl -fsSL https://install.orchestratia.com/uninstall-linux | bash -s -- --force

Removes: systemd service orchestratia-agent, /etc/orchestratia/, /opt/orchestratia-agent/, /var/log/orchestratia/, the pip package.

macOS

If you installed via Homebrew (the recommended path):

brew services stop orchestratia-agent
brew uninstall orchestratia-agent
brew untap orchestratiahq/tap
rm -rf "$HOME/Library/Application Support/Orchestratia"

If you installed via the legacy script (install-macos.sh):

curl -fsSL https://install.orchestratia.com/uninstall-macos | bash

Windows

irm https://install.orchestratia.com/uninstall-windows | iex

To preserve config (so a future reinstall reuses your registered identity):

$env:ORC_KEEP_CONFIG=1; irm https://install.orchestratia.com/uninstall-windows | iex

Removes: scheduled task OrchestratiAgent, %LOCALAPPDATA%\Orchestratia\ (exe, wrappers, logs, config), PATH entries, running processes.

After uninstalling

The server still appears in your dashboard as Online for up to 90 seconds (until the next heartbeat is missed), then flips to Offline. To remove it from the dashboard entirely, open the server detail page and click Delete.

Troubleshooting

Server not appearing after install?

  • Check that the daemon is running: systemctl status orchestratia-agent (Linux) or launchctl list | grep orchestratia (macOS)
  • Verify the registration token hasn't expired
  • Check firewall rules — the daemon needs outbound HTTPS access to your hub

Agent not picking up tasks?

  • Make sure the session is active (green status)
  • Ensure the AI agent (Claude Code, etc.) is running inside the session
  • Check that the task is assigned to the correct session

Need help?