This guide covers day-to-day development from a Trellis source checkout. It uses the same simple local setup as Starting Trellis: NATS runs in a container, while the Trellis runtime and Console run from source.

What you need

• Git
• Deno v2+
• a Rust toolchain
• podman
• the trellis CLI installed (see Install the Trellis CLI)

1. Prepare a local runtime bundle

Generate local NATS, Trellis config, credentials, keys, and data directories:

trellis local init --out ~/trellis

Start NATS from that bundle:

podman run --replace --detach --name trellis-nats \
  --publish 127.0.0.1:4222:4222 \
  --publish 127.0.0.1:8080:8080 \
  --publish 127.0.0.1:8222:8222 \
  --volume "$HOME/trellis/nats/nats.conf:/etc/nats/nats.conf:ro,Z" \
  --volume "$HOME/trellis/nats/jwt.conf:/etc/nats/jwt.conf:ro,Z" \
  --volume "$HOME/trellis/nats/data:/data:Z" \
  docker.io/library/nats:latest \
  -c /etc/nats/nats.conf

The generated config is ready for local username/password login. You do not need a GitHub or OIDC application for the first local admin account.

2. Clone and prepare the repo

git clone https://github.com/qlever-llc/trellis.git
cd trellis

Generate contract artifacts from a clean checkout:

cd js
deno task prepare
cd ..

deno task prepare is bootstrap-safe because it runs through trellis-generate; you do not need a running Trellis instance to generate SDKs and manifests. Rust-first workflows can run the same repo-local generation step with cargo xtask prepare.

During active contract work, run a watcher in a separate terminal:

cd js
deno task prepare:watch

The Rust workspace exposes the same workflow as cargo xtask prepare-watch.

3. Apply shared infrastructure

trellis infra apply \
  --servers 127.0.0.1 \
  --trellis-creds ~/trellis/nats/creds/trellis-auth.creds \
  --auth-creds ~/trellis/nats/creds/auth-auth.creds

4. Start the Trellis runtime

cd js/services/trellis
TRELLIS_CONFIG="$HOME/trellis/trellis/config.jsonc" deno task dev

The runtime starts on http://localhost:3000 with file watching enabled. Trellis serves the built-in portal from the source tree during this flow.

5. Create and log in as an admin

When Trellis starts for the first time, it creates the initial local admin identity and prints an admin setup URL. Open that URL in your browser and set the password. Then start the CLI login flow:

trellis login http://localhost:3000
trellis whoami

6. Start Console

cd js/apps/console
cp .env.example .env
deno task dev

Open http://localhost:5173 and log in with the local admin username and password.

Development workflow

• Runtime changes: edit files under js/services/trellis/ or js/packages/; the service watcher restarts automatically.
• Console changes: edit files under js/apps/console/; Vite HMR applies changes in place.
• Contract changes: run cd js && deno task prepare, or keep cd js && deno task prepare:watch running.
• CLI changes: run cargo build -p trellis-cli in the rust/ directory, then re-run trellis ... commands.
• Type checking: run deno task -c js/deno.json check.
• Tests: run deno task -c js/deno.json test:contracts or deno task -c js/deno.json test:auth.

Verify

curl http://127.0.0.1:8222/healthz
curl -i http://localhost:3000/_trellis/portal
curl -I http://localhost:5173/
trellis whoami