Skip to content
Astromesh Astromesh

Quick Start

Nexus ships as Kustomize manifests: one overlay per environment that brings up nexus, its PostgreSQL, the Redis for conversational memory and the Astromesh runtime pool. This guide deploys the dev overlay and then walks the API from a new user to a priced run.

Prerequisites

Section titled “Prerequisites”
ToolWhy
A Kubernetes clusterk3s, Kind, EKS, GKE or AKS. nexus needs a Kubernetes client at boot.
kubectlApplies the overlay (Kustomize is built in).
An LLM provider keyThe runtime pool calls the model your agent declares.
Pull access to ghcr.io/monaccode/astromesh-nexusThe image is published to GHCR.

Deploy

Section titled “Deploy”

  1. Create the namespace and the secrets. The overlays deliberately keep secrets out of git; deploy/overlays/dev/secrets.yaml is the template.

    Terminal window
    NS=nexus-dev
    kubectl create namespace $NS
    kubectl create secret docker-registry ghcr-pull -n $NS \
      --docker-server=ghcr.io --docker-username=<user> --docker-password=<PAT read:packages>
    kubectl create secret generic nexus-postgres -n $NS \
      --from-literal=POSTGRES_USER=nexus --from-literal=POSTGRES_PASSWORD=<pwd>
    kubectl create secret generic nexus-db -n $NS \
      --from-literal=database-url='postgres://nexus:<pwd>@nexus-postgres:5432/nexus?sslmode=disable'
    kubectl create secret generic nexus-secrets -n $NS \
      --from-literal=jwt-secret=<random> \
      --from-literal=operator-token=<at least 32 bytes> \
      --from-literal=connections-key=$(openssl rand -hex 32)
    kubectl create secret generic astromesh-runtime-secrets -n $NS \
      --from-literal=MOONSHOT_API_KEY=<key>

    The password in nexus-db must match nexus-postgres. operator-token and connections-key are optional: without the first, operators sign in with the operator role only; without the second, connections answer 503.

  2. Apply the overlay.

    Terminal window
    kubectl apply -k deploy/overlays/dev
    kubectl rollout status deployment/nexus -n nexus-dev

    nexus creates and migrates its own schema on first boot, so there is no migration job.

  3. Reach the API. The overlay ships an Ingress; for a local cluster, port-forward instead:

    Terminal window
    kubectl port-forward -n nexus-dev svc/nexus 8080:8080
    curl -s localhost:8080/healthz

Publish and run an agent

Section titled “Publish and run an agent”

  1. Register a user and create a tenant. Tenant and key management take a JWT.

    Terminal window
    N=http://localhost:8080
    JWT=$(curl -s $N/auth/register -H 'Content-Type: application/json' \
      -d '{"email":"me@example.com","password":"a-long-password","displayName":"Me"}' | jq -r .accessToken)
    

    TENANT=$(curl -s $N/api/v1/tenants -H "Authorization: Bearer $JWT" \
      -H 'Content-Type: application/json' -d '{"displayName":"Acme"}' | jq -r .id)

  2. Create an API key for programmatic access. The raw key is returned once.

    Terminal window
    KEY=$(curl -s $N/api/v1/tenants/$TENANT/keys -H "Authorization: Bearer $JWT" \
      -H 'Content-Type: application/json' -d '{"label":"quickstart"}' | jq -r .rawKey)

  3. Publish an agent. The body is the astromesh/v1 spec, as YAML or JSON. Publishing creates version 1.

    Terminal window
    curl -s $N/api/v1/agents -H "X-API-Key: $KEY" --data-binary @- <<'EOF'
    apiVersion: astromesh/v1
    kind: Agent
    metadata:
      name: support-bot
    spec:
      identity: { display_name: Support Bot }
      model:
        primary:
          provider: openai_compat
          model: kimi-k2.6
          endpoint: https://api.moonshot.ai/v1
          api_key_env: MOONSHOT_API_KEY
      prompts:
        system: You answer customer questions briefly.
      orchestration: { pattern: react }
    EOF

  4. Run it.

    Terminal window
    curl -s $N/api/v1/agents/support-bot/run -H "X-API-Key: $KEY" \
      -H 'Content-Type: application/json' \
      -d '{"query":"What are your opening hours?","session_id":"user-42"}'
    {
      "invocation_id": "…",
      "status": "ok",
      "answer": "…",
      "usage": { "tokens_in": …, "tokens_out": …, "by_model": [ … ] },
      "credits_charged_micros": …,
      "pricing_status": "priced"
    }

    Reusing session_id keeps the conversation: the runtime’s memory is keyed by tenant, agent and session.

  5. Look at what it cost.

    Terminal window
    curl -s $N/api/v1/agents/support-bot/metrics -H "X-API-Key: $KEY"
    curl -s $N/api/v1/usage -H "X-API-Key: $KEY"

Next

Section titled “Next”