Skip to content

Develop with Tilt

One command starts humagen's API, the console with hot reload and a database that keeps conversations across restarts, and restarts only what a change needs. It is a Tilt extension, deploy/tilt/dev/Tiltfile, so a project built on humagen uses the same workflow with its own command and spec, rather than keeping a launcher of its own.

make tilt                                   # tilt up -f dev.Tiltfile; open http://127.0.0.1:5173
tilt up -f dev.Tiltfile -- --memory         # no Docker; nothing is kept
tilt up -f dev.Tiltfile -- --mock           # sign in as a persona instead of as admin
tilt up -f dev.Tiltfile -- --spec examples/dev/humagen.yaml   # real models
tilt down -f dev.Tiltfile                   # stop everything; the database is kept

It needs Tilt, Go, Node.js and pnpm, and Docker for the database (not with --memory). The root Tiltfile is a different setup: humagen on a local Kubernetes cluster through its Helm chart (deploy).

What runs

Resource What it is Runs again when
binary go build of the command into .humagen-dev/bin a watched Go file changes
doctor Versions, addresses, where state is kept, humagen config check on the spec, credentials not set a spec file or the env file changes; the API waits for it at start
postgres Postgres 17 in Docker on 127.0.0.1:5434, volume NAME-dev_postgres-data never; tilt down stops it and keeps the volume
api humagen serve on 127.0.0.1:8080; ready when /healthz answers the binary or a spec file (branding, agents) changes
console-deps pnpm install --frozen-lockfile the lockfile changes
console The Vite dev server on 127.0.0.1:5173, proxying /api and /auth to the API never: Vite reloads the page itself, and the API keeps running

Tilt is the only supervisor: it starts, restarts and stops each process. run.sh checks the process's port first, so a port another process holds stops the start with that process named instead of a bind error, waits for the database, then becomes the process (exec), so the signal Tilt sends reaches it and nothing is left holding the port. Agents' files and published files go to .humagen-dev/workspace, so they are kept too.

A changed spec restarts the API and reruns doctor together. A spec that does not check fails both, with the same error, and the API starts again once the file is fixed. Branding is read at start, so a branding change shows after the restart and a reload of the page.

In a project built on humagen

A project that calls humagen.Main with its own options, and has its own spec, loads the extension pinned to the release its go.mod requires. examples/tilt/Tiltfile is a copy to start from:

v1alpha1.extension_repo(name = 'humagen', url = 'https://github.com/urmzd/humagen', ref = 'v0.38.0')
v1alpha1.extension(name = 'humagen-dev', repo_name = 'humagen', repo_path = 'deploy/tilt/dev')
load('ext://humagen-dev', 'humagen_dev')

humagen_dev(
    name = 'ignite',               # its own database volume
    go_package = './cmd/ignite',   # its own command
    specs = ['config'],            # its branding and agents, watched
    env_file = '.env.dev',         # model keys, from a file git ignores
    credentials = ['ANTHROPIC_API_KEY'],
)

ref is a humagen release that has deploy/tilt/dev. The binary is built from the project's go.mod; the console runs from the extension's checkout, so doctor warns when the two versions differ. While changing humagen beside the project, load from a local checkout instead and the console follows it: load('../humagen/deploy/tilt/dev/Tiltfile', 'humagen_dev'). Add .humagen-dev/ and the env file to the project's .gitignore.

Options

Relative paths are from the Tiltfile that calls humagen_dev.

Option Default Meaning
name humagen Names the database's Docker project and volume
specs none Spec files or directories passed as -f, watched
agent_specs none Agent JSON files passed as -agent-specs, watched
go_dir the calling Tiltfile's directory The Go module the binary is built in
go_package ./cmd/humagen The main package
go_watch humagen's Go sources, else go_dir What rebuilds the binary
humagen_dir the checkout the extension is in Where the console runs from
port, console_port 8080, 5173 Loopback ports
console True False runs the API alone
auth dev -auth: dev signs everyone in as admin; mock offers personas from a provider on 127.0.0.1:8081
seed on with no spec The example agents on the offline model
state postgres postgres keeps conversations; memory does not; None leaves it to the spec
postgres_url none A database of your own instead of the one in Docker
postgres_port 5434 The Docker database's loopback port
data_dir .humagen-dev The binary, and agents' and published files
env_file, env none Variables for every process; env wins
credentials none Variables the project needs; doctor lists those not set
strict_credentials False True holds the API back while one is missing
extra_args none More humagen serve flags; they win over the spec

What has been checked

The Tiltfiles were run with Tilt's functions stubbed out, to check the commands and dependencies they produce for the default, --memory --mock and --spec ... --no-console. The commands themselves were run: the build, doctor on no spec, on a spec with unset keys (fatal only with strict_credentials) and on a spec that does not check (fatal); the API and console through run.sh, the console's proxy answering /api/me; a second start on a held port refused with the holder named; and both stopped by SIGTERM with their ports free and no child left. Not run here: tilt up itself, and the Docker database (no Docker daemon), so conversations surviving a restart rests on the Postgres stores' own tests and on seeding being idempotent.