telos is a goal-oriented agent runtime.
Use telos to turn software goals into running services. Maintain and manage goals, not code.
curl -fsSL https://usetelos.ai/install.sh | sh
telos --versionThe installer downloads checksummed telos and telosd binaries for your
platform (macOS and Linux, amd64/arm64).
Write a goal and save it as SPEC.md:
---
version: 0.1.0
name: hello-service
platform: local
---
# Goal
Build a small HTTP service with `/healthz`, tests, and local run instructions.Run it as a bounded task:
telos run SPEC.md --workspace . --until 3 # at most 3 review cycles
telos run SPEC.md --workspace . --until 30m # at most 30 minutesLocal runs execute goal turns through pi, an open-source coding agent:
npm install -g @earendil-works/pi-coding-agentTelos defaults local runs to openai-codex/gpt-5.5 with high thinking effort.
Authenticate that provider in pi before your first run, or select another pi
model with --model:
telos run SPEC.md --model openai-codex/gpt-5.5 --thinking highModel names use <provider>/<model-id>. Set TELOS_MODEL to keep a different
default across runs; use TELOS_THINKING to change the thinking effort.
Providers, models, and credentials are managed by pi; run pi and use
/login, and see
pi's model documentation
for configuration details.
run executes bounded task work. apply creates or updates a durable
controller session that keeps reconciling desired state.
telos login
telos apply SPEC.md
telos list --cloudHosted deployments pin their effective model when they are created. Override
the platform default with --model and --thinking (or TELOS_MODEL and
TELOS_THINKING). These settings seed new deployments; existing deployments
retain their pinned model.
To steer an existing controller, edit the same disk spec and apply it back to the same session:
telos apply SPEC.md --session sess_...The spec frontmatter version is the package version published to Telos Cloud,
so the reviewed file, package ref, and backend record stay aligned:
version: 0.1.1Managed Cloud is in early access; sign up at usetelos.ai.
Fair Source (FSL-1.1), converts to Apache-2.0 two years after each release
go test ./...
go build ./cmd/telos ./cmd/telosdRelease builds use Bazel:
bazel test //...
scripts/publish-release.sh