Quickstart

From zero to a running agent in about 90 seconds.

Before you start

You need three things:

A Linux x86-64 host (arm64 and macOS builds are not published yet) with outbound HTTPS to https://cp.agentina.digcub-lab.com on port 443.
An activation token — a one-time string that starts with act_.
The trusted-keys file URL or path your operator gave you. The agent verifies license signatures against this set.

Don't have a token yet? If your account is set up, mint one at /portal/tokens. If you don't have a portal account yet, your operator will hand-deliver these during onboarding.

1. Install the agent

One command. The installer downloads the signed binary, verifies the cosign signature, and registers it under systemd.

bash

(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/install.sh -o install.sh && \
  curl -fsSL https://dl.agentina.digcub-lab.com/v1/dist/installer/install.sh.sig -o install.sh.sig && \
  cosign verify-blob --key release.pub --signature install.sh.sig install.sh && \
  sudo env AGENTINA_TOKEN=act_xxx AGENTINA_COSIGN_PUBKEY="$PWD/release.pub" bash install.sh)

The installer creates an unprivileged agentina system user and installs to /opt/agentina/<version>/. It refuses any tarball whose cosign signature doesn't match a production key — so a MITM'd install fails fast.

2. Verify it's running

From the command line

bash

sudo systemctl status agentina
sudo -u agentina /opt/agentina/current/agentina status

Expect activated: true, a non-empty agent_id, and a license.health: ok line.

From the customer portal

Sign in at /portal/login and open the Agents page. Your new agent should appear within 60 seconds with status active.

3. Confirm end-to-end

Watch the heartbeat land in journalctl:

bash

sudo journalctl -u agentina -f -n 50

You'll see a line like heartbeat: active → active every 60 seconds. That's the agent reporting to the Control Plane and getting back "keep going." You're live.

4. Where to go next

Run your first real piece of work — concrete walk-through.
Pick the right agent type — decision guide.
Scale to a fleet — when one agent isn't enough.
Glossary — every term in one place.

If something goes wrong

"invalid activation token"

Tokens are single-use and expire after 14 days. The first machine to redeem claims the token; if you ran the installer twice, the second run fails here. Mint a fresh one from /portal/tokens.

"failed to reach control plane"

The agent only initiates outbound HTTPS. Check egress to https://cp.agentina.digcub-lab.com on port 443. Corporate proxies generally need an explicit allow-list entry; set HTTPS_PROXY in /etc/agentina/agent.env if you go through one.

Anything else

Full troubleshooting checklist (logs, common errors, how to file a ticket) lives at /docs/troubleshooting.