Install a service from source

This guide covers installing and running a service from its source tree during development. You need the contract source file checked out locally.

If you are deploying a published service from an OCI image, see Install a service from an image instead.

What you need

• a running Trellis environment
• the trellis CLI installed (see Install the Trellis CLI)
• admin access to the Trellis instance
• the service source tree checked out locally

1. Log in as an admin

Create or refresh the local administrator session:

trellis --nats-servers localhost auth login \
  --auth-url http://localhost:3000 \
  --provider github

Confirm the session is active:

trellis auth status

2. Verify the contract

Before installing, verify the contract source compiles and is well-formed:

trellis contracts verify --source ./contracts/my_service.ts

3. Install from source

trellis service install --source ./contracts/my_service.ts

The CLI reads the contract definition directly from source, generates a session key, and installs the contract.

The CLI will:

• generate a new Ed25519 session seed locally
• derive the public session key for the service
• infer defaults such as display name, description, and namespaces from the contract
• show an installation review before sending the request

4. Store the seed immediately

After a successful install, the CLI prints:

installed service contract
sessionKey=<public-key>
contractId=trellis.my-service@v1
contractDigest=<digest>
seed=<private-seed>
store the seed securely; it will not be shown again

Save the seed to your env file or secret store immediately. The CLI will not print it again.

5. Start the service process

Pass the seed and NATS details as environment variables and start the service with your normal command:

export MY_SERVICE_SESSION_KEY_SEED="<seed printed by trellis service install>"
export NATS_SERVERS=localhost
export NATS_SENTINEL_CREDS=/path/to/sentinel.creds

deno task dev

or:

npm run dev

6. Upgrade when the contract changes

When you change the contract, upgrade the installed service identity:

trellis service upgrade --source ./contracts/my_service.ts

If you need to target a specific installed service:

trellis service upgrade --source ./contracts/my_service.ts --seed <private-seed>

Upgrade keeps the service key the same and updates the installed contract digest. Restart the service process after upgrading.

What install actually grants

Installation is not only metadata storage. It is the control-plane step that determines what the service is allowed to do.

Trellis derives service access from:

• the service-owned RPC, event, and subject surfaces declared in the contract
• explicit dependencies declared under uses
• runtime-managed resource bindings created during install or upgrade

Useful flags

Flag	Command	What it does
--display-name	service install	Overrides the default display name inferred from the contract
--description	service install	Stores an explicit operator-facing description
--namespace	service install	Adds extra namespaces beyond the ones inferred from the contract
--inactive	service install	Installs the service in an inactive state
-f	both	Skips the interactive confirmation prompt
--service-key	service upgrade	Targets a specific installed service
--seed	service upgrade	Resolves the service key from a local seed

Development loop

1. update schemas and the defineContract(...) module
2. trellis contracts verify --source
3. trellis service upgrade --source
4. restart the service
5. confirm the expected RPCs, events, and bindings work