Self-Hosted Installation

Install Agent Studio on your own server. Everything runs locally — your code never leaves your infrastructure.

System Requirements

Component	Minimum	Recommended
OS	Ubuntu 22.04 / Debian 12 / AlmaLinux 8+ / Rocky 8+ / RHEL 8+	Ubuntu 24.04 LTS
CPU	2 cores (x64)	4+ cores
RAM	4 GB	8+ GB
Disk	20 GB free	50+ GB SSD
Network	Outbound HTTPS	Static IP + domain
Claude CLI	Anthropic Claude Code (`claude login`)

Quick Install

One command installs everything: PostgreSQL, Redis, Node.js, nginx, and all Agent Studio services.

Step 1: Generate an install token from the portal

# Get your token at https://agentina.digcub-lab.com/portal/install
# Then run:

Step 2: Run the installer

(d="$(mktemp -d)" && cd "$d" && \
  { [ "$(uname -s)" = Linux ] || { echo "ERROR: run this on the Linux server (Ubuntu/Debian/Alma/Rocky), not on your own computer." >&2; false; }; } && \
  { cosign version >/dev/null 2>&1 || { echo "cosign not found - installing it (needs sudo)..." && \
      { sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y cosign >/dev/null 2>&1 || \
        { a="$(uname -m)"; case "$a" in \
            x86_64|amd64) a=amd64; h=8b24b946dd5809c6bd93de08033bcf6bc0ed7d336b7785787c080f574b89249b;; \
            aarch64|arm64) a=arm64; h=3b2e2e3854d0356c45fe6607047526ccd04742d20bd44afb5be91fa2a6e7cb4a;; \
            *) echo "ERROR: no official cosign binary for $a - install cosign yourself, then run this again." >&2; false;; \
          esac && \
          curl -fsSL https://github.com/sigstore/cosign/releases/download/v2.4.1/cosign-linux-$a -o cosign && \
          echo "$h  cosign" | sha256sum -c - >/dev/null && \
          sudo install -m 0755 cosign /usr/local/bin/cosign; }; } && \
      cosign version >/dev/null 2>&1; } || \
    { echo "ERROR: cosign could not be installed. Install it (https://docs.sigstore.dev/cosign/system_config/installation/) and run this again." >&2; false; }; } && \
  printf '%s\n' '-----BEGIN PUBLIC KEY-----' 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqB2uMAdD03ndJD4VmW6d6J98NPSL' '8mEmFbUK2ZLJc7l6b87qF67oMh5KmWl76rcNTxlK+D5Y4F9BOn50a58+3Q==' '-----END PUBLIC KEY-----' > release.pub && \
  curl -fsSL https://dl.agentina.digcub-lab.com/v1/dist/installer/studio.sh -o studio.sh && \
  curl -fsSL https://dl.agentina.digcub-lab.com/v1/dist/installer/studio.sh.sig -o studio.sh.sig && \
  cosign verify-blob --key release.pub --signature studio.sh.sig studio.sh && \
  sudo env AGENTINA_TOKEN=act_YOUR_TOKEN AGENTINA_COSIGN_PUBKEY="$PWD/release.pub" bash studio.sh)

The command carries Agentina's release public key and checks the installer's signature before running it as root; the installer then verifies everything it downloads against the same key. The command first checks for cosign and, if it is missing, installs it for you (apt, otherwise the official release binary checked against a pinned SHA-256), so there is nothing to set up beforehand. Run it on the Linux server itself. Key fingerprint (sha256 of the key file): 2c0075860522f697d5e29181ce5518b7af622e621d8df492dad07e224a87dce2

What Gets Installed

PostgreSQL 16 — task database, project metadata
Redis — job queue, real-time streaming
Controller — API server, task orchestration
Executor — spawns Claude sessions, runs tasks
Guard — license enforcement, heartbeat
UI — Next.js dashboard (port 9802)
nginx — reverse proxy (port 9800, configurable)
systemd — auto-start on boot, restart on failure

Architecture


Your Server
├── nginx (port 9800) ── reverse proxy
│   ├── /api/*  → Controller (9801)
│   ├── /ws/*   → Controller (9801) WebSocket
│   └── /*      → UI (9802)
│
├── Controller (9801) ── API, orchestration
├── Executor ── Claude sessions, task execution
├── Guard (9803) ── license, heartbeat to cloud
├── UI (9802) ── Next.js dashboard
│
├── PostgreSQL (system) ── database
├── Redis (9810) ── dedicated job queue
│
└── /var/lib/agentina-studio/ ── state, license, keys

All ports are configurable via environment variables.
Does NOT conflict with other services on ports 80, 443, 3000, 5432, 6379.

The only external connection is the Guard → Control Plane heartbeat (HTTPS, every 60s). All code execution happens locally on your server.

Claude CLI Setup

After installation, set up Claude Code on the server:

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Authenticate
claude login

# Verify
claude --version

Open http://your-server-ip:9800 in your browser
Create your admin account
Create a project pointing to your repository
Run your first task

Port Reference

Service	Default Port	Env Override	Notes
nginx (public)	9800	AGENTINA_HTTP_PORT	Customer-facing dashboard
Controller	9801	AGENTINA_CONTROLLER_PORT	localhost only
UI	9802	AGENTINA_UI_PORT	localhost only
Guard	9803	AGENTINA_GUARD_PORT	localhost only
Redis	9810	AGENTINA_REDIS_PORT	Dedicated instance
PostgreSQL	5432	—	Uses system PostgreSQL

All ports are chosen to avoid conflicts with common services (80, 443, 3000, 5432, 6379, 8080). Safe to install alongside existing applications.

Service Management

# Status
systemctl status agentina-controller
systemctl status agentina-executor
systemctl status agentina-guard
systemctl status agentina-ui

# Logs
journalctl -u agentina-controller -f
journalctl -u agentina-executor -f

# Restart
systemctl restart agentina-controller
systemctl restart agentina-executor

Upgrading

(d="$(mktemp -d)" && cd "$d" && \
  { [ "$(uname -s)" = Linux ] || { echo "ERROR: run this on the Linux server (Ubuntu/Debian/Alma/Rocky), not on your own computer." >&2; false; }; } && \
  { cosign version >/dev/null 2>&1 || { echo "cosign not found - installing it (needs sudo)..." && \
      { sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y cosign >/dev/null 2>&1 || \
        { a="$(uname -m)"; case "$a" in \
            x86_64|amd64) a=amd64; h=8b24b946dd5809c6bd93de08033bcf6bc0ed7d336b7785787c080f574b89249b;; \
            aarch64|arm64) a=arm64; h=3b2e2e3854d0356c45fe6607047526ccd04742d20bd44afb5be91fa2a6e7cb4a;; \
            *) echo "ERROR: no official cosign binary for $a - install cosign yourself, then run this again." >&2; false;; \
          esac && \
          curl -fsSL https://github.com/sigstore/cosign/releases/download/v2.4.1/cosign-linux-$a -o cosign && \
          echo "$h  cosign" | sha256sum -c - >/dev/null && \
          sudo install -m 0755 cosign /usr/local/bin/cosign; }; } && \
      cosign version >/dev/null 2>&1; } || \
    { echo "ERROR: cosign could not be installed. Install it (https://docs.sigstore.dev/cosign/system_config/installation/) and run this again." >&2; false; }; } && \
  printf '%s\n' '-----BEGIN PUBLIC KEY-----' 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqB2uMAdD03ndJD4VmW6d6J98NPSL' '8mEmFbUK2ZLJc7l6b87qF67oMh5KmWl76rcNTxlK+D5Y4F9BOn50a58+3Q==' '-----END PUBLIC KEY-----' > release.pub && \
  curl -fsSL https://dl.agentina.digcub-lab.com/v1/dist/installer/studio.sh -o studio.sh && \
  curl -fsSL https://dl.agentina.digcub-lab.com/v1/dist/installer/studio.sh.sig -o studio.sh.sig && \
  cosign verify-blob --key release.pub --signature studio.sh.sig studio.sh && \
  sudo env AGENTINA_COSIGN_PUBKEY="$PWD/release.pub" bash studio.sh --upgrade)

Upgrades preserve your database, license, and configuration. Only the runtime binaries are replaced.

Troubleshooting

Service won't start

Check logs: journalctl -u agentina-controller -n 50. Common causes: PostgreSQL not running, Redis not running, missing environment variables.

Tasks fail with "claude not found"

Install Claude CLI: npm install -g @anthropic-ai/claude-code && claude login

License expired

Contact support to renew. The dashboard remains readable; only task execution is paused.

Can't connect to dashboard

Check nginx: nginx -t && systemctl status nginx. Ensure port 9800 is open in your firewall (ufw allow 9800).

Files module — "Permission denied" when creating folders

The controller needs a writable workspace directory. Fresh installs (v0.2.0+) set this up automatically. If upgrading from an older version, run:

sudo mkdir -p /home/agentina
sudo chown -R agentina:agentina /home/agentina
echo 'FILES_ROOT=/home/agentina' | sudo tee -a /etc/agentina/studio.env
sudo systemctl restart agentina-controller

Controller won't start — ADMIN_PASSWORD not set

Since v0.1.1 the controller requires ADMIN_PASSWORD in the environment. Set it in /etc/agentina/studio.env and restart:

echo 'ADMIN_PASSWORD=your-secure-password' >> /etc/agentina/studio.env
systemctl restart agentina-controller

Fresh installs (v0.1.1+) generate this automatically. Only needed if upgrading from v0.1.0.

Security

All runtime bundles are obfuscated and integrity-verified at startup. The license guard runs independently and enforces machine binding, signed grace state, and tamper detection. See the security page for details.

Uninstall

systemctl stop agentina-guard agentina-controller agentina-executor agentina-ui
systemctl disable agentina-guard agentina-controller agentina-executor agentina-ui
rm /etc/systemd/system/agentina-*.service
systemctl daemon-reload
rm -rf /opt/agentina-studio
# Optionally: rm -rf /var/lib/agentina /etc/agentina