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. Choose your connection tier:
    • Agent — Full daemon with live streaming, file transfer, and SSH tunneling (recommended)
    • Skill Only — Lightweight Claude Code hooks (no daemon needed, perfect for quick evaluation)
    • SSH Tunnel — Hub-initiated SSH connection (zero inbound firewall rules)
  4. Set a label and expiry time
  5. Copy the install command

Install the Agent Daemon

Paste the install command on your server. It looks like this:

curl -fsSL https://raw.githubusercontent.com/kumarimlab/orchestratia-agent/main/scripts/install-linux.sh | sudo bash -s -- TOKEN

The script will:

  • Install the orchestratia-agent Python package
  • Register with your hub using the one-time token
  • Set up a systemd service (Linux) or launchd plist (macOS)
  • Start the daemon automatically

Once installed, 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
  • Claude Code Skills — Lightweight integration via hooks and CLI (no daemon needed)
  • AI Agent Guide — Complete CLI reference for AI agents using the orchestratia command

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?