Documentation

Quick Start

Prerequisites

COSMIOS does not install or manage agents. You must install and authenticate your agent (Claude Code, Codex, etc.) on the machine before using COSMIOS. COSMIOS observes, reports, and controls - but the agent runs natively on your machine with its own configuration.

Install COSMIOS

npm i -g cosmios
cosmios init

This will:

1. Open the COSMIOS dashboard in your browser
2. Approve your machine from the browser
3. Save the config to ~/.cosmios/config.json
4. Start the runner automatically

Your machine is now online and ready to receive runs from the dashboard.

Alternatively, you can register manually with an API key:

cosmios register

Register a Machine

There are two ways to register a machine:

Method 1: API Key (recommended)

cosmios register

Go to the dashboard > Machines > enter a name > click Register. Copy the API key and paste it in the CLI when prompted.

Method 2: Device Auth Flow

cosmios init

Opens a browser window with a verification code. Approve the device in the browser and the machine registers automatically. No API key copy-paste needed.

Start the Runner

cosmios start

The runner connects to COSMIOS via WebSocket and polls for pending runs every 3 seconds. It runs in the foreground - use tmux, screen, or a systemd service to keep it running in the background.

To check the runner status from another terminal:

cosmios status

Background with systemd

# /etc/systemd/system/cosmios.service
[Unit]
Description=COSMIOS Runner
After=network.target

[Service]
ExecStart=/usr/bin/env cosmios start
Restart=always
User=your-user
WorkingDirectory=/home/your-user

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now cosmios

Dispatch a Run

Runs can be dispatched from the dashboard or the CLI.

From the Dashboard

Open the terminal panel (bottom right) or the Tasks page. Select a machine, agent, workspace path, and enter your prompt. Click the send button to dispatch.

From the CLI

cosmios run --workspace ~/my-project --task "Fix the auth bug in login.ts"

The CLI streams logs in real-time until the run completes.

Options

• --agent codex - Use Codex instead of Claude Code (default)

Missions

Missions let you chain multiple tasks into a sequential pipeline. Each mission contains cards - individual instructions dispatched one after another to your agents.

Creating a Mission

Open the Missions page from the dashboard. Enter a title, select a workspace, and click Create. Then add cards with instructions and select which agent should execute each one.

How Cards Execute

Click Play to start the mission. Cards execute sequentially: card 1 runs first, and when it completes, card 2 starts automatically. Each subsequent card receives context from previous cards (a summary of what was accomplished).

• If a card completes, the next card starts automatically
• If a card fails, the mission pauses and you can resume later
• Click Pause to stop the current card mid-execution
• Click Resume to restart from where you left off

Action Items

When a card finishes, COSMIOS analyzes the run logs and extracts any tasks that require your manual action (e.g. configuring environment variables, enabling cloud APIs, setting up DNS). These appear as a checklist in the mission view and on the dashboard overview.

Live Terminal

While a card is running, the execution output streams in real-time below the card pipeline. The card statuses refresh automatically every 3 seconds.

Notifications

You receive an email when a mission completes (all cards done) or fails. No emails are sent for individual card completions to avoid noise.

Snapshot & Rollback

Before every run, COSMIOS automatically creates a git commit in the workspace:

git add -A && git commit -m "COSMIOS snapshot before run {run_id}"

If anything goes wrong, click Rollback on the run detail page. COSMIOS will git reset --hard to the snapshot commit, restoring the exact state before the agent ran.

Rollback is available after every run (completed, failed, or cancelled).

CLI Reference

Supported Agents

Agents must be installed and logged in on the target machine. COSMIOS does not manage agent credentials, API keys, or model selection - the agent uses its own local configuration. COSMIOS wraps the agent process to capture events, logs, and metrics.

• Claude Code - Full support. Uses --output-format stream-json for structured logs. Supports --continue for session resume.
• Codex - Full support. Uses --json for JSONL event stream. Native session resume via codex exec resume.
• Aider - Coming soon.
• Gemini CLI - Coming soon.

API KeysPro+

Programmatic access to your COSMIOS data. Generate an API key from the dashboard (Developers page). The key is shown once at creation.

Authentication

Pass your key in the Authorization header:

curl -H "Authorization: Bearer csu_your_key_here" \
  https://www.cosmios.dev/api/v1/machines

Rate Limits

API keys are limited to 60 requests per minute. Rate limit headers are included in every response:

• X-RateLimit-Limit - Max requests per window
• X-RateLimit-Remaining - Requests left
• X-RateLimit-Reset - Window reset timestamp

WebhooksPro+

Receive real-time HTTP notifications when events happen on your machines. Configure webhooks from the dashboard (Developers > Webhooks tab).

Event Types

Payload Format

{
  "event": "run.completed",
  "timestamp": "2026-03-07T12:00:00Z",
  "data": {
    "run_id": "abc123",
    "workspace": "/home/user/project",
    "agent": "claude-code",
    "status": "completed"
  }
}

Signature Verification

Every webhook request includes an X-Cosmios-Signature header. Verify it with HMAC-SHA256 using your webhook signing secret:

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(requestBody)
  .digest('hex');

if (signature === req.headers['x-cosmios-signature']) {
  // Valid request from COSMIOS
}

REST APIPro+

All endpoints are under /api/v1/ and require Bearer authentication.

FAQ