Ask Acton

Ask Acton is the backend and browser widget for an Acton guide assistant. The guide can remain a static mdBook site on GitHub Pages. Browser code calls this service, and this service calls OpenAI with the API key kept server-side.

Services

• ask-acton: TypeScript/Fastify API for /api/ask.
• playground: TypeScript/Fastify API and page for running Acton snippets through a Docker sandbox.
• caddy: TLS and reverse proxy for ask.acton.guide and play.acton.guide.
• public/ask-acton.*: static widget assets for the mdBook theme.
• infra/glesys: OpenTofu scaffold for the first GleSYS VM.

Local Development

npm install
cp .env.example .env
$EDITOR .env
npm run dev

The health check is:

curl http://localhost:8787/healthz

The public aggregate stats page is:

open http://localhost:8787/stats

Ask endpoint:

curl http://localhost:8787/api/ask \
  -H 'content-type: application/json' \
  -d '{"question":"How do actors store mutable state in Acton?"}'

Ask Acton stores completed chat sessions as JSON files under ASK_LOG_DIR. A session is considered complete after ASK_SESSION_IDLE_SECONDS without another interaction. The logs are not served over HTTP and contain only the conversation payload and answer, not IP addresses or user agents.

Summarize stored sessions with:

npm run build
npm run analyze:ask-logs -- /var/lib/ask-acton/ask-logs

Run the playground service locally:

npm run dev:playground

The playground page is then available at:

open http://localhost:8788/

The playground stats page is:

open http://localhost:8788/stats

The playground expects Docker to be available and PLAYGROUND_ACTON_IMAGE to point at an image containing acton and runacton.

Set GITHUB_GIST_TOKEN to enable playground sharing. The playground creates unlisted gists through the server; the token is never sent to the browser.

Build the default runner image:

docker build -t ask-acton/acton-runner:tip runner-image

Index the Guide

Create or update a vector store from a local checkout of the Acton guide:

export OPENAI_API_KEY=...
npm run index:docs

To update an existing vector store:

export OPENAI_VECTOR_STORE_ID=vs_...
npm run index:docs

By default, the indexer uploads the current files and then removes previously indexed files with source=acton-guide. This keeps old guide pages from remaining searchable after a docs rewrite without leaving the assistant empty if a new indexing run fails. Set INDEX_REPLACE_SOURCE=false to append instead.

The Acton repository has a GitHub Actions workflow for this. On pushes to docs/acton-guide/**, it checks out this repository, runs the indexer against the pushed guide sources, and tags indexed files with the pushed commit SHA. The workflow needs these repository secrets in actonlang/acton:

ASK_ACTON_OPENAI_API_KEY
ASK_ACTON_VECTOR_STORE_ID
ACTBOT_PAT

Set the printed OPENAI_VECTOR_STORE_ID in .env before starting the service.

Ask Acton's system prompt lives in src/prompt.ts. The prompt already asks for inferred signatures when type errors need more context. Prefer acton sig <module-or-name> when the error involves an imported module, public name, or dependency API. Use acton --sigs <source-file> or acton build --sigs <source-file> only as a fallback for older builds or direct source-file inspection.

Deploy

The first deployment target is one GleSYS VM that runs Ask Acton, the playground service, the Acton runner image, and Caddy. The guide itself can still be published as a static GitHub Pages site.

Provisioning is driven with OpenTofu through Docker:

export GLESYS_USERID=cl31994
export GLESYS_TOKEN=...
./scripts/tofu -chdir=infra/glesys init
./scripts/tofu -chdir=infra/glesys plan
./scripts/tofu -chdir=infra/glesys apply
./scripts/tofu -chdir=infra/glesys output

The current production VM is:

server_id = kvm4221419
ipv4      = 188.126.83.249
ipv6      = 2a02:750:23:f7::f7
hostname  = ask-acton-01

Create these DNS records before starting Caddy:

ask.acton.guide   A     188.126.83.249
ask.acton.guide   AAAA  2a02:750:23:f7::f7
play.acton.guide  A     188.126.83.249
play.acton.guide  AAAA  2a02:750:23:f7::f7

Caddy obtains certificates during startup. If DNS does not already resolve to the VM, certificate issuance will fail.

After cloud-init has finished, create the initial service tree on the VM:

ssh acton@188.126.83.249
git clone https://github.com/actonlang/ask-acton.git
cd ask-acton
cp .env.example .env
$EDITOR .env
docker build -t ask-acton/acton-runner:tip runner-image
docker compose up -d --build

Routine deployments are driven from this repository with just. The VM currently stores a plain source tree rather than a Git checkout, so the deploy recipe sends the committed local HEAD with git archive over SSH, preserving the remote .env file and Docker volumes.

just deploy-ask     # rebuild and restart only Ask Acton
just deploy-play    # rebuild and restart playground and Caddy
just deploy         # rebuild and restart all services
just status
just logs ask-acton

The deploy recipes refuse to run with a dirty local worktree. Commit the change first so the deployed tree is reproducible. Override the target host or directory with ASK_ACTON_HOST and ASK_ACTON_REMOTE_DIR when needed.

The .env file must include OPENAI_API_KEY. Ask Acton also needs OPENAI_VECTOR_STORE_ID from the indexing step if it should answer from the guide instead of only the base model context. Playground sharing needs GITHUB_GIST_TOKEN with gist access. The default playground settings allow up to 10 active Acton snippets with a 15 second timeout per snippet.

Ask Acton conversation logging is enabled by default. Set ASK_LOGGING_ENABLED=false to disable it, or adjust ASK_SESSION_IDLE_SECONDS to change when an inactive chat is flushed to disk.

To deploy only the playground before Ask Acton has an OpenAI key:

cp .env.example .env
docker build -t ask-acton/acton-runner:tip runner-image
docker compose up -d --build --no-deps playground caddy

This starts play.acton.guide without starting the ask-acton service. Caddy still loads the full Caddyfile, so ask.acton.guide may have a TLS certificate but will not have a working backend until Ask Acton is started.

Verify the host and services:

cloud-init status --wait
docker --version
docker compose ps
curl -fsS https://play.acton.guide/healthz

For the full Ask Acton deployment, also verify:

curl -fsS https://ask.acton.guide/healthz

See docs/PROVISIONING.md for the full runbook and local state notes.

Playground Runner

The same VM hosts the first Acton playground, but it is a separate service from Ask Acton. See docs/RUNNER.md for the security model and the remaining hardening work before broad public use.