Installing Agent Studio¶

This guide walks you through standing up Agent Studio — the web console for the XiansAi platform — against a XiansAi Server. It covers two paths:

• Run locally from source (for development or evaluation).
• Run from DockerHub using the published 99xio/agent-studio image (for staging and production).

Prerequisites¶

Configuration: the .env file¶

Everything Agent Studio needs is supplied through environment variables. The repository ships an .env.example you can copy and fill in — it is the single source of truth for every supported setting.

Copy it to the file your run mode expects:

# Local development reads .env.local
cp .env.example .env.local

# Docker / production reads .env.production
cp .env.example .env.production

Required variables¶

These must be set for Agent Studio to start and connect to the platform.

# Generate a NEXTAUTH_SECRET
openssl rand -base64 32

Authentication providers (at least one)¶

Agent Studio signs users in via OAuth/OIDC. Configure at least one provider; leave the others empty to disable them.

Application variables¶

Option A — Run locally from source¶

Best for development, customizing the UI, or evaluating against a local server.

# 1. Clone the repository
git clone https://github.com/XiansAiPlatform/agent-studio.git
cd agent-studio

# 2. Install dependencies
npm install

# 3. Create your environment file
cp .env.example .env.local
#    Then edit .env.local — set XIANS_SERVER_URL, XIANS_APIKEY,
#    NEXTAUTH_URL=http://localhost:3010, NEXTAUTH_SECRET, and a provider.

# 4. Start the dev server (hot reload, port 3010)
npm run dev

Open http://localhost:3010 and sign in.

To run a production build locally instead of the dev server:

npm run build
npm run start

Option B — Run from DockerHub¶

The platform team publishes multi-platform (AMD64 + ARM64) images to DockerHub as 99xio/agent-studio. This is the recommended path for staging and production — no source checkout or Node toolchain required.

1. Prepare the environment file¶

cp .env.example .env.production
# Edit .env.production with your real values:
#   XIANS_APIKEY, XIANS_SERVER_URL,
#   NEXTAUTH_URL=https://your-domain.com,
#   NEXTAUTH_SECRET (openssl rand -base64 32),
#   and at least one auth provider.

2. Pull and run the image¶

# Pull the latest stable image
docker pull 99xio/agent-studio:latest

# Run it
docker run -d \
  --name agent-studio \
  -p 3000:3000 \
  --env-file .env.production \
  --restart unless-stopped \
  99xio/agent-studio:latest

Pin to a specific release instead of latest for reproducible deploys, e.g. 99xio/agent-studio:v1.0.0.

3. Verify¶

curl http://localhost:3000/api/health
# {"status":"healthy","timestamp":"...","uptime":123}

Then browse to your NEXTAUTH_URL and sign in.

Running with Docker Compose¶

If you prefer Compose, point a service at the published image and your env file:

services:
  agent-studio:
    image: 99xio/agent-studio:latest
    ports:
      - "3000:3000"
    env_file:
      - .env.production
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

docker compose up -d
docker compose logs -f agent-studio

Updating¶

docker compose pull && docker compose up -d
# or, for a plain docker run:
docker pull 99xio/agent-studio:latest
docker rm -f agent-studio && docker run -d --name agent-studio \
  -p 3000:3000 --env-file .env.production --restart unless-stopped \
  99xio/agent-studio:latest

First-run checklist¶

1. Server is up and bootstrapped — you have a XIANS_SERVER_URL and a SysAdmin XIANS_APIKEY. See Platform Bootstrapping.
2. .env file filled in — required variables set, plus at least one auth provider.
3. NEXTAUTH_URL matches reality — it must equal the URL users actually open, or sign-in callbacks fail.
4. Redirect URIs registered — for each enabled provider, register {NEXTAUTH_URL}/api/auth/callback/<provider>.
5. Health check passes — GET /api/health returns healthy.
6. First login resolves to SysAdmin — sign in with the identity whose user id equals the bootstrap email.

Troubleshooting¶

What's Next?¶

• Agent Studio Overview — what the Studio does once it's running: roles, agent descriptors, tool logs, theming, uploads, and heartbeats.
• Platform Bootstrapping — initialize a fresh server and mint your first API key.