agent-quickstart.yaml

api:
  name: Axis CLI API
  base_url: http://127.0.0.1:<PORT>
  version: "1.0"
  description: >
    Axis is the Eternum onchain agent CLI. It discovers active worlds, authenticates
    with Cartridge Controller, and runs an LLM-driven tick loop that observes game
    state and executes on-chain actions. In headless mode it exposes an HTTP API,
    SSE event stream, and stdin control interface.
  docs_url: https://docs.realms.world/development/axis/overview
  source_repo: https://github.com/bibliothecadao/eternum

installation:
  method: shell_script
  command: "curl -fsSL https://github.com/bibliothecadao/eternum/releases/latest/download/install-axis.sh | bash"
  pin_version: "VERSION=v0.1.0 bash"
  verify: "axis --version"
  prerequisites:
    - "One model provider API key (e.g. ANTHROPIC_API_KEY)"
    - "For source builds: Node.js 22+, pnpm, Bun"

authentication:
  type: none
  note: >
    The HTTP API runs locally and requires no auth token. Authentication to the
    Eternum game is handled separately via Cartridge Controller (browser OAuth
    or password method). Session tokens are stored in ~/.eternum-agent/.cartridge/<world>/.
  cartridge_auth_methods:
    - name: browser_interactive
      description: "Opens browser automatically for interactive login"
      command: "axis auth <world>"
    - name: password
      description: "Direct password auth, no browser required"
      command: "axis auth <world> --method=password --username=<user> --password=<pass>"
    - name: redirect_url
      description: "Complete auth with redirect URL captured from browser"
      command: "axis auth <world> --redirect-url=<url>"
    - name: session_data
      description: "Complete auth with raw base64 session data"
      command: "axis auth <world> --session-data=<base64>"

configuration:
  env_file: "~/.eternum-agent/.env"
  variables:
    required:
      - name: ANTHROPIC_API_KEY
        type: string
        description: "Required when MODEL_PROVIDER=anthropic (default)"
      - name: OPENAI_API_KEY
        type: string
        description: "Required when MODEL_PROVIDER=openai"
    optional:
      - name: MODEL_PROVIDER
        type: string
        default: "anthropic"
        options: ["anthropic", "openai", "openrouter", "google"]
        description: "LLM provider selection"
      - name: MODEL_ID
        type: string
        default: "claude-sonnet-4-5-20250929"
        description: "Model identifier"
      - name: CHAIN
        type: string
        default: "slot"
        options: ["slot", "sepolia", "mainnet"]
        description: "Blockchain network"
      - name: SLOT_NAME
        type: string
        description: "Auto-select discovered world by name"
      - name: GAME_NAME
        type: string
        default: "eternum"
        description: "Session/game namespace"
      - name: TICK_INTERVAL_MS
        type: integer
        default: 60000
        description: "Agent tick interval in milliseconds"
      - name: LOOP_ENABLED
        type: boolean
        default: true
        description: "Auto-start tick loop on launch"
      - name: ETERNUM_AGENT_HOME
        type: string
        default: "~/.eternum-agent"
        description: "Runtime root directory"
      - name: RPC_URL
        type: string
        description: "Manual RPC endpoint override (skips world discovery)"
      - name: TORII_URL
        type: string
        description: "Manual Torii indexer endpoint override"
      - name: WORLD_ADDRESS
        type: string
        description: "Manual world contract address override"
      - name: PRIVATE_KEY
        type: string
        description: "Private key for private-key auth mode"
      - name: ACCOUNT_ADDRESS
        type: string
        description: "Account address for private-key auth mode"

cli_commands:
  - name: axis_run_tui
    syntax: "axis"
    alias: "axis run"
    description: "Run Axis in TUI (terminal UI) mode with interactive world picker"
    use_when: "Running manually on a laptop with a TTY"

  - name: axis_run_headless
    syntax: "axis run --headless --world=<name>"
    description: "Run Axis in headless server mode, emitting NDJSON to stdout"
    use_when: "VPS, CI, fleet orchestration, agent-controlled environments"
    required_flags:
      - name: "--world"
        type: string
        required: true
        description: "Target world name. Required in headless mode."
    optional_flags:
      - name: "--api-port"
        type: integer
        description: "Enable HTTP API on specified port"
      - name: "--api-host"
        type: string
        description: "API bind host (default: 127.0.0.1)"
      - name: "--stdin"
        type: boolean
        description: "Enable stdin JSON command stream"
      - name: "--verbosity"
        type: string
        options: ["quiet", "actions", "decisions", "all"]
        description: "Output verbosity filter for NDJSON events"
      - name: "--auth"
        type: string
        options: ["session", "privatekey"]
        description: "Auth strategy"
      - name: "--json"
        type: boolean
        description: "JSON output for command responses"

  - name: axis_worlds
    syntax: "axis worlds"
    description: "List all discovered worlds across slot, sepolia, and mainnet"

  - name: axis_auth
    syntax: "axis auth <world>"
    description: "Authenticate with a world via Cartridge Controller"
    flags:
      - name: "--all"
        type: boolean
        description: "Target all discovered worlds"
      - name: "--status"
        type: boolean
        description: "Check session status instead of generating auth URL"
      - name: "--method"
        type: string
        options: ["password"]
        description: "Auth method (password = no browser required)"
      - name: "--username"
        type: string
        description: "Username for password auth"
      - name: "--password"
        type: string
        description: "Password for password auth"
      - name: "--redirect-url"
        type: string
        description: "Complete auth with the redirect URL captured from browser"
      - name: "--session-data"
        type: string
        description: "Complete auth with raw base64 session data"
      - name: "--callback-url"
        type: string
        description: "Public callback endpoint for headless VPS auth"
      - name: "--timeout"
        type: integer
        description: "Approval wait timeout in ms"
      - name: "--json"
        type: boolean
        description: "Output result as JSON"

  - name: axis_doctor
    syntax: "axis doctor"
    description: "Validate configuration and diagnose common issues"

  - name: axis_init
    syntax: "axis init [world]"
    description: "Manually seed runtime directories and config (optional; all dirs are auto-created on first run)"

endpoints:
  - name: queue_prompt
    method: POST
    path: /prompt
    description: "Queue a natural-language prompt for the agent to execute on the next tick"
    requires_api_port: true
    parameters:
      - name: content
        type: string
        location: body
        required: true
        description: "Natural language instruction for the agent"
    request_content_type: "application/json"
    request_example:
      content: "Build a farm at your main realm"
    response:
      type: object
      description: "Acknowledgment that the prompt was queued"
    errors:
      - code: 400
        message: "Bad Request"
        action: "Check that body is valid JSON with a 'content' field"
      - code: 500
        message: "Internal Server Error"
        action: "Check agent logs; the agent process may have crashed"

  - name: get_status
    method: GET
    path: /status
    description: "Get the current agent status including world info, loop state, and session"
    requires_api_port: true
    parameters: []
    response:
      type: object
      description: "Agent status snapshot"
      fields:
        - name: world
          type: string
          description: "Active world name"
        - name: loopEnabled
          type: boolean
          description: "Whether the tick loop is running"
        - name: tickIntervalMs
          type: integer
          description: "Current tick interval in milliseconds"
        - name: sessionActive
          type: boolean
          description: "Whether a valid session exists"
    errors:
      - code: 500
        message: "Internal Server Error"
        action: "Agent process may not be running; restart axis"

  - name: get_state
    method: GET
    path: /state
    description: "Get a full snapshot of the current world state observed by the agent"
    requires_api_port: true
    parameters: []
    response:
      type: object
      description: "World state snapshot as observed by agent"
    errors:
      - code: 500
        message: "Internal Server Error"
        action: "Agent process may not have loaded world state yet; wait for first tick"

  - name: subscribe_events
    method: GET
    path: /events
    description: "Subscribe to the agent's Server-Sent Events (SSE) stream of NDJSON events"
    requires_api_port: true
    parameters:
      - name: verbosity
        type: string
        location: query
        required: false
        description: "Filter events: quiet, actions, decisions, all"
    response:
      type: stream
      content_type: "text/event-stream"
      description: "SSE stream of NDJSON event objects"
      event_types:
        - name: startup
          description: "Agent started"
        - name: session
          description: "Session established or changed"
        - name: decision
          description: "Agent made a strategic decision"
        - name: action
          description: "Agent executed an on-chain action"
        - name: prompt
          description: "Prompt was queued or processed"
        - name: heartbeat
          description: "Periodic heartbeat"
        - name: config
          description: "Configuration changed"
        - name: error
          description: "An error occurred"
        - name: shutdown
          description: "Agent shutting down"
    verbosity_filters:
      quiet: ["error", "session", "shutdown"]
      actions: ["error", "session", "shutdown", "action"]
      decisions: ["error", "session", "shutdown", "action", "decision", "heartbeat", "prompt", "startup", "config"]
      all: ["error", "session", "shutdown", "action", "decision", "heartbeat", "prompt", "startup", "config", "tick"]

  - name: update_config
    method: POST
    path: /config
    description: "Update runtime configuration without restarting the agent"
    requires_api_port: true
    parameters:
      - name: changes
        type: array
        location: body
        required: true
        description: "Array of config change objects with 'path' and 'value'"
    request_content_type: "application/json"
    request_example:
      changes:
        - path: "tickIntervalMs"
          value: 30000
    updatable_config_paths:
      - tickIntervalMs
      - loopEnabled
      - modelProvider
      - modelId
      - dataDir
    response:
      type: object
      description: "Confirmation of applied config changes"
    notes:
      - "Some backend fields (world connection details) require restart in headless mode"
    errors:
      - code: 400
        message: "Bad Request"
        action: "Verify the 'changes' array has valid 'path' and 'value' fields"

  - name: shutdown
    method: POST
    path: /shutdown
    description: "Gracefully shut down the axis agent process"
    requires_api_port: true
    parameters: []
    response:
      type: object
      description: "Shutdown initiated confirmation"
    errors:
      - code: 500
        message: "Internal Server Error"
        action: "Process may already be shutting down"

  - name: auth_callback
    method: GET
    path: /auth/callback
    alias_method: POST
    description: "Cartridge Controller OAuth callback endpoint. Used during browser-based auth flows."
    requires_api_port: true
    parameters:
      - name: code
        type: string
        location: query
        required: false
        description: "OAuth authorization code from Cartridge"
      - name: state
        type: string
        location: query
        required: false
        description: "OAuth state parameter"
    response:
      type: object
      description: "Auth completion result"

stdin_control:
  description: >
    When --stdin flag is set (or stdin is non-TTY), send one JSON object per line
    to control the agent programmatically.
  enabled_when: "--stdin flag is passed OR stdin is non-TTY"
  message_types:
    - type: prompt
      schema:
        type: "prompt"
        content: "<string>"
      description: "Queue a prompt for the agent"
      example: '{"type":"prompt","content":"Scout north"}'
    - type: config
      schema:
        type: "config"
        changes:
          - path: "<string>"
            value: "<any>"
      description: "Update runtime configuration"
      example: '{"type":"config","changes":[{"path":"tickIntervalMs","value":45000}]}'
    - type: shutdown
      schema:
        type: "shutdown"
      description: "Initiate graceful shutdown"
      example: '{"type":"shutdown"}'

ndjson_events:
  description: "Headless mode emits newline-delimited JSON objects to stdout"
  verbosity_levels:
    quiet: "error, session, shutdown"
    actions: "quiet + action"
    decisions: "actions + decision, heartbeat, prompt, startup, config"
    all: "decisions + tick"

agent_notes:
  idempotency: "POST /prompt is not idempotent; avoid duplicate submissions"
  retry_logic: >
    On 500 errors, wait 5s and retry. On connection refused, ensure axis is running
    with --api-port and the correct port.
  polling: >
    If SSE (GET /events) is unavailable, poll GET /status every tickIntervalMs ms.
    Default tick interval is 60000ms (60 seconds).
  fleet_pattern: >
    Use 'axis auth --all --json' to authenticate all worlds, then launch one
    axis process per world on separate ports.