---
title: Server & CLI
icon: terminal
description: Daemon + CLI for managing workspaces from the shell.
---

## Overview

Two companion packages to the core SDK:

- **[`@struktoai/mirage-server`](https://github.com/strukto-ai/mirage/tree/main/typescript/packages/server)**, a Fastify daemon that owns workspaces in-process and exposes them over HTTP (`/v1/workspaces`, `/v1/jobs`, ...).
- **[`@struktoai/mirage-cli`](https://github.com/strukto-ai/mirage/tree/main/typescript/packages/cli)**, a `commander` CLI that speaks to the daemon. Mirrors Python's `mirage` CLI 1:1.

The CLI is stateless. Long-running state lives in the daemon; the CLI auto-spawns one on the first `mirage workspace create` if none is running.

## Install

```bash
npm install -g @struktoai/mirage-cli
```

This pulls in `@struktoai/mirage-server` transitively (the CLI spawns the daemon from the server package's installed `bin/daemon.js`).

## Create a workspace

Write a YAML config:

```yaml
# config.yaml
mounts:
  /:
    resource: ram
    mode: write
```

Then:

```bash
mirage workspace create config.yaml
```

The CLI:
1. Validates the YAML + interpolates `${VAR}` env references (fails fast if any are missing).
2. Auto-spawns a daemon on `127.0.0.1:8765` if none is reachable.
3. Sends `POST /v1/workspaces` and prints the returned detail as JSON.

## Run commands in a workspace

```bash
# synchronous, blocks until the command finishes
mirage execute -w <workspace-id> -c "ls /"

# background, returns a job id immediately; poll/wait later
mirage execute --bg -w <workspace-id> -c "wc -l /large.csv"
mirage job wait <job-id>
```

## Workspace lifecycle

| Command | Purpose |
|---|---|
| `mirage workspace create <config.yaml>` | Create; auto-spawns daemon if needed. |
| `mirage workspace list` | List active workspaces. |
| `mirage workspace get <id> [--verbose]` | Show one workspace's detail. |
| `mirage workspace delete <id>` | Stop and remove. |
| `mirage workspace clone <id> [--id NEW] [--override over.json]` | Clone; fresh local resources, reused remote ones. |
| `mirage workspace snapshot <id> <out.tar>` | Snapshot to tar. |

## Sessions

```bash
mirage session create <workspace-id> --id agent_a
mirage session list <workspace-id>
mirage session delete <workspace-id> <session-id>
```

## Daemon lifecycle

```bash
mirage daemon status      # health + PID + uptime
mirage daemon stop        # graceful shutdown (POST /v1/shutdown + SIGTERM fallback)
mirage daemon restart     # stop; next CLI command auto-spawns fresh
mirage daemon kill        # SIGKILL; last resort
```

## Configuration

Precedence (highest first):

1. **`MIRAGE_DAEMON_URL`** env var, e.g. `http://127.0.0.1:9000`.
2. **`MIRAGE_TOKEN`** env var, bearer token passed as `Authorization: Bearer <token>`.
3. **`~/.mirage/config.toml`** `[daemon]` table:
   ```toml
   [daemon]
   url = "http://127.0.0.1:8765"
   auth_token = ""
   persist_dir = ""
   idle_grace_seconds = 30
   ```

## Python parity

The daemon speaks the same `/v1/...` protocol as Python's `mirage` CLI. A Python CLI client can talk to a Node daemon and vice versa. The CLI subcommand tree matches Python's `mirage/cli/*.py` file-for-file.

## Where things live

| File | Purpose |
|---|---|
| [`packages/server/src/app.ts`](https://github.com/strukto-ai/mirage/blob/main/typescript/packages/server/src/app.ts) | Fastify app factory. |
| [`packages/server/src/routers/`](https://github.com/strukto-ai/mirage/tree/main/typescript/packages/server/src/routers) | health / workspaces / sessions / execute / jobs. |
| [`packages/server/src/bin/daemon.ts`](https://github.com/strukto-ai/mirage/blob/main/typescript/packages/server/src/bin/daemon.ts) | `mirage-daemon` bin. |
| [`packages/cli/src/main.ts`](https://github.com/strukto-ai/mirage/blob/main/typescript/packages/cli/src/main.ts) | CLI program wiring. |
| [`packages/cli/src/{workspace,session,execute,provision,job,daemon}.ts`](https://github.com/strukto-ai/mirage/tree/main/typescript/packages/cli/src) | Per-subcommand modules. |
| [`packages/cli/src/client.ts`](https://github.com/strukto-ai/mirage/blob/main/typescript/packages/cli/src/client.ts) | HTTP client + auto-spawn. |
