@kybernesis/exe

Run eve agents on exe.dev VMs with subscription-backed model access, process supervision, and an optional Slack binding.

Run an agent as a service

Deployed agents should run under their installed systemd service so they start again after a VM reboot.

Unlike eve dev, eve start does not load .env.local itself. The service must export the file's assignments before starting the agent:

set -a
. ./.env.local
set +a
npx eve start

Merely sourcing the file creates shell variables that may not be inherited by the child process. set -a marks assignments for export, and set +a restores the shell's normal behavior afterward.

Install the package-owned unit from the agent directory:

bash node_modules/@kybernesis/exe/scripts/install-service.sh

kyb upgrade refreshes an existing generated unit when its content or mode drifts, but does not create a missing unit or restart the service. Keep persistent host-specific settings in a systemd drop-in instead of editing the generated unit, so package refreshes do not erase them:

sudo systemctl edit <name>-agent
# writes /etc/systemd/system/<name>-agent.service.d/override.conf
sudo systemctl daemon-reload
sudo systemctl restart <name>-agent

For inspection or repair, the installer also supports --unit-path, --print-unit, and --refresh-unit. The refresh mode rewrites the unit and runs systemctl daemon-reload without enabling or restarting the service.

Once the unit exists, restart the agent through the service instead of running scripts/eve-server.sh independently. Running both gives two supervisors control of the same agent and can start two servers against the same durable .eve store.

Workflow callback base preflight

hostPreflight() checks WORKFLOW_LOCAL_BASE_URL when it is set: it trims the value, removes one trailing slash, and sends a GET to <base>/eve/v1/health from this machine. The check fails on a network error, on a 15-second timeout, or on any non-2xx response.

The variable is the base for every workflow queue delivery, including the ones the host makes to itself — not only for callbacks from remote work. A URL that remote peers can reach but the host cannot therefore fails every queue delivery and stops the agent from processing workflow work at all, while looking correct in the environment file. The preflight exists because that failure names fetch failed and nothing else.

Model reach chosen at boot

exeModelReach() picks one of three routes from KYB_MODEL_REACH each time the agent starts, so the owner can change it through the setup route (POST /eve/v1/kyb/setup/env in @kybernesis/manage) without editing agent/agent.ts:

| KYB_MODEL_REACH | Route | Model id | Window | | --- | --- | --- | --- | | gateway | the exe LLM integration (exeModel) | EXE_MODEL, provider-prefixed | 200k | | byok | the provider's own API with ANTHROPIC_API_KEY or OPENAI_API_KEY | EXE_MODEL; its anthropic/ or openai/ prefix picks the key | 200k | | claude-sub | the loopback Claude OAuth proxy (claudeSubscription) | claude-opus-5 | 1M |

import { defineAgent } from "eve";
import { createAnthropic } from "@ai-sdk/anthropic";
import { createOpenAI } from "@ai-sdk/openai";
import { exeModelReach } from "@kybernesis/exe";

export default defineAgent({
  ...exeModelReach({ reach: "gateway", model: "anthropic/claude-sonnet-5", createOpenAI, createAnthropic }),
  limits: { maxInputTokensPerSession: false },
});

Unset, it builds the reach and model the file names: kyb init --host=exe writes exactly the route it used to hard-code. A requested route that cannot run (an unknown value, BYOK without its key or prefix) boots the default instead with one [exe] KYB_MODEL_REACH=… not used line in the journal, rather than throwing: the route that would switch it back lives inside the agent. The setup status route reports the same decision. resolveExeReach() is the pure decision, for scripts.

Models on a client's own subscription

Three providers, one purpose: a client already pays for a seat, and an agent that bills metered API usage on top buys the same capability twice.

import { defineAgent } from "eve";
import { createAnthropic } from "@ai-sdk/anthropic";
import { claudeSubscription, CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW } from "@kybernesis/exe";

export default defineAgent({
  model: claudeSubscription({ model: "claude-opus-5", createAnthropic }),
  modelContextWindowTokens: CLAUDE_SUBSCRIPTION_CONTEXT_WINDOW,
});

grokSubscription() and eve's experimental_chatgpt() are the same idea for their vendors, and all three read a login rather than an API key.

Claude differs in one way that matters operationally. Grok and ChatGPT credentials are files a CLI keeps fresh; a Claude subscription is refreshed by a local proxy that owns the OAuth exchange, so there is a process to keep alive rather than only a file to keep current. claudeSubscription() speaks the ordinary Anthropic Messages API to that proxy, and the API key it passes is a placeholder the proxy replaces — a real key there would bill metered usage and quietly defeat the whole arrangement.

The proxy must bind to loopback. It spends a paid subscription and requires no credential of its own, so a port on a public interface is an open gateway to that subscription. claudeSubscription() refuses a non-loopback URL unless requireLoopback: false is passed deliberately, and preflight reports both liveness and exposure:

await hostPreflight({ claudeProxyUrl: "http://127.0.0.1:3333/v1" });

Standing the proxy up

One script, on the host the agent runs on. kyb init installs it for an exe host; otherwise copy it from this package's scripts/.

bash scripts/claude-subscription.sh up      # pull + run, bound to 127.0.0.1
bash scripts/claude-subscription.sh login   # "Sign in with Claude" — never an API key
bash scripts/claude-subscription.sh status  # signed in? exposed off-host?

up is idempotent and the sign-in survives it: credentials live in a named volume, so a restarted or recreated container does not send anyone back through a browser. status distinguishes running from signed in — the proxy answers /health as soon as it listens but /ready only once it holds a credential, and conflating those is how a proxy looks healthy and answers nothing.

The sign-in dies on a schedule — about every 28 days

This is the one to diary. The access token refreshes hourly and will do so happily for weeks, which tells you nothing: underneath it the refresh token carries its own fixed expiry, roughly 28 days from the browser sign-in. Using it does not extend it. When it passes, the refresh fails, the proxy writes the credential file back with empty token strings, and every turn 401s with OAuth access token has expired.

Nothing in place recovers — not reload, not a restart, not waiting. Only login, because only a browser can mint a new refresh token.

There is a third state /ready cannot see, and it cost a morning on Sid: signed in with a dead credential. /ready reports that a credential was loaded, not that it is still valid, so it answers 200 over a blanked file while the API 401s — status claimed "signed in, answering" through an outage. status now probes /v1/models too, and reads the refresh expiry out of the volume so it can warn before the cliff rather than after:

✓ sid-claude-subscription: signed in and authenticating, answering on 127.0.0.1:3333
✓ sign-in valid for 27d
✓ loopback only

It escalates at 7 days (!) and 3 days (✗), and says EXPIRED Nd ago past it. Run status on a schedule for every subscription-backed agent — this failure is silent, presents as a model outage, and sends people to Anthropic's status page instead of to a browser. Reading the expiry needs root on the host; without it that line is omitted rather than guessed.

up builds and uses the patched image on its own (once per host, a few minutes), and moves a container still on the stock image over to it, keeping the sign-in. prepare starts that build in the background for callers that cannot wait (it exits 0 when ready, 3 while building, 1 when the host cannot build); the app's Claude sign-in uses it. CLAUDE_PROXY_NO_BUILD=1 skips the build, and CLAUDE_PROXY_IMAGE still picks an image outright. By hand:

bash scripts/claude-subscription.sh build-patched
CLAUDE_PROXY_IMAGE=claude-auth-proxy:a62318f-provider-tools bash scripts/claude-subscription.sh recreate

The published image renames provider-defined tools, which Anthropic validates by name, so web_search fails with tools.N.web_search_20250305.name: Input should be 'web_search' — an error naming a tool index and a schema, pointing nowhere near a proxy in the middle. The fix is in patches/ and is not upstream. build-patched applies it from a pinned revision so it cannot be lost in a rebuild, which is exactly how it was lost once before, when it lived only inside a Docker image tag. Selecting between providers at boot — one env var, one stable context window per process — is the pattern to copy; switching per turn would change the context window under a running session.

Output cap

Every call through claudeSubscription() carries maxOutputTokens: 16000 unless the call sets its own. Without it the provider asks for the model's maximum (max_tokens: 128000 on claude-opus-5) on every request, and because a subscription is a shared per-minute output budget, the subscription agent is the first thing to fail under load. Change it per agent with maxOutputTokens: 32000, or disable it with maxOutputTokens: false. The constant is exported as CLAUDE_SUBSCRIPTION_MAX_OUTPUT_TOKENS.

iMessage through Linq

@kybernesis/exe/linq carries what a Linq line needs on a VM: linqEnvCredentials() reads LINQ_API_KEY and LINQ_WEBHOOK_SECRET with errors that name the missing variable, and linqSenderIdentity() is the channel's onMessage. It resolves each sender's number through the control plane's channel identity, so a linked person runs as themselves, an unlinked number gets one text with a claim link and no turn, and a refused sender gets silence. eve add @kybernesis/linq writes the channel; the manage setup action linq.verify writes the two keys and registers the webhook.

The agent's computer

Moved to its own package: @kybernesis/computer (the DockerComputer provider, Chrome, the launcher bar, the open_browser guard and the connector-first rule). Install it with eve add @kybernesis/computer.