Understand the work.
Keep the thread.

Use Jentra from setup to a finished result

Follow this route for a first real Project. You can use hosted Jentra, Local Docker or your own Cloudflare account. Jentra coordinates the work; your connected model or agent performs it.

1. 1

   Choose where Jentra runs

   Use the hosted experiment for the quickest start, Local Docker for private evaluation, or your own Cloudflare account for an always-reachable installation.

2. 2

   Create and verify your account

   Sign up, follow the email verification link when hosted, sign in and complete onboarding. Local Docker keeps accounts local and does not require email verification.

3. 3

   Create a Project

   Use a Project as the durable home for related source, participants, work, memory and policy.

4. 4

   Describe the current result

   State what should be true when the work is finished, what must not change and how the result should be checked. The first prompt is initial intent, not an irreversible final goal.

5. 5

   Choose the lightest work mode

   Use Direct for exploration, Quick Task for one bounded change, or Managed Journey for consequential, parallel or long-running work.

6. 6

   Connect the source

   Import a Git repository, use an existing compatible remote, bring files, or start empty. Private imports remain blocked until an approved runtime can resolve the credential reference.

7. 7

   Connect your agent and model

   Use a compatible IDE, CLI, runtime host, MCP connection or agent harness. Jentra does not bundle a model or silently charge for one.

8. 8

   Set authority and limits

   Choose what agents may do autonomously, which tools they may use and which delivery, spending or policy boundaries still require a person.

9. 9

   Start bounded work

   Jentra gives each Assignment its objective, relevant context, capability envelope and isolated or deliberately collaborative World.

10. 10

    Follow what matters

    Use activity, attention, checkpoints and Ask why to understand progress without watching every model message.

11. 11

    Review the contribution

    Inspect the result, provenance, claims, evidence, known limitations and unresolved questions.

12. 12

    Verify and accept

    Run proportionate checks. Independent verification must come from an eligible participant other than the work author.

13. 13

    Deliver or continue

    Compose accepted work, then merge, publish or deploy only through a separately authorised action. Keep, archive or clean up Worlds according to the Project policy.

Choose the lightest work mode

Not every action needs a Journey. Jentra adds structure in proportion to consequence and coordination.

Use language that fits the work

Choose the closest work kind during onboarding. It changes the language and suggested checks, while the same coordination model keeps direction, authority, evidence and decisions connected.

Find the guide for your next task

These routes take you directly to the relevant instructions. Start with the end-to-end route when you are unsure.

Journeys, Assignments and Runs

A Journey carries consequential work from shared direction to a verified result. It remains understandable even when participants change.

How continuity works

Each assigned agent receives a versioned handoff containing the Journey direction, its role, current accepted context, relevant prior results, dependencies, boundaries and remaining work. Consequential callbacks bind to an alignment hash; stale agents must refresh before continuing.

Change direction without rewriting history

Projects learn as they move. The first prompt records initial intent, but it may not remain the final direction.

1. 1

   Pause affected work

   Stop new consequential results from being accepted against the old direction.

2. 2

   Record what changed

   Capture the new direction, why it changed and the evidence or decision behind it.

3. 3

   Assess active work

   Keep unaffected Assignments. Replace, revise or supersede anything that no longer serves the current result.

4. 4

   Refresh every affected agent

   Issue new Assignment context before work resumes. Treat incompatible earlier results as historical evidence, not current deliverables.

For a small change, revise the bounded Assignment. For a change that alters the purpose of the work, begin a new Managed Journey inside the same Project so the earlier history remains intact.

Agents, teams and autonomy

Jentra is compatible with different agent harnesses. It coordinates authority and shared state; the connected harness executes the work.

Manage active agents reliably

Open Agent operations inside a Managed Journey to see responsibility, current execution, alignment, recovery and authority without reading every model message.

Truthful liveness

Queued, starting, working, using tools, waiting, checkpointed, unresponsive and terminal states remain distinct. Heartbeat age and observation source stay visible.

Continuous alignment

When Direction or accepted state changes, only affected Assignments require refresh. Stale results cannot advance canonical state.

Safe recovery

Failed, cancelled or silent Runs preserve checkpoints. A recovery starts a lineage-linked successor rather than rewriting the original attempt.

Hierarchy

Lead agents may coordinate bounded subordinate Assignments. Delegation never expands capability or approval authority.

Resources and placement

See concurrency, delegation policy, effect receipts, runtime capacity and exact eligibility failures. Provider spending remains not reported unless a trusted provider receipt supplies it.

Outcome evidence

Completed and failed Runs, accepted Contributions, rework and recoveries are Journey-specific evidence, not a universal ranking of models.

Worlds and ordinary Git

A World is an isolated or deliberately collaborative workspace for an Assignment. For code, it is backed by ordinary Git concepts.

• Each World begins from a known baseline and records its repository and commit identity.
• Scoped credentials enforce which repository and capabilities a participant may use.
• Jentra negotiates the lightest mode the work and provider support: metadata, sparse checkout, full checkout or an externally managed World.
• Jentra inspects Git history and tree changes to compute diffs and provenance.
• Clean contributions compose normally; overlapping paths become focused repair work rather than a whole-branch restart.
• You can keep using local Git, an IDE or a terminal. Jentra does not trap work in the web app.
• A failed replacement leaves the existing World and source intact.
• Cleanup is configurable. Connected source repositories are never automatically deleted.

Evidence, checks and decisions

Jentra separates “work completed” from “result trusted.”

Required checks

Candidate, post-composition and pre-delivery checks can be required by policy. Jentra distinguishes missing, failed and stale results, and binds each result to the candidate, dependencies and current Direction revision.

Evidence

Tests, outputs, documents, diffs, citations or other proof attached to a claim.

Independent verification

A separate eligible participant checks the claim. Work authors cannot independently approve themselves.

Ask why

Inspect provenance, reasons and supporting evidence for a result or decision.

Resolution

The chosen composition of accepted work. Checks and verification do not automatically merge, publish, deploy or spend.

Memory and context

Jentra keeps current work aligned and can recall approved knowledge without turning every transcript into permanent memory.

Manage memory in Settings

Usage and limits

Hosted Jentra is capped to prevent unexpected cost and abuse. Limits are configuration, not permanent product assumptions.

• See your allowance, current use, warnings and reset time on the Usage page.
• Limits cover Projects, active Journeys, concurrent and daily Runs, storage and monthly work units.
• Execution also has bounded time, retries, delegation depth and tool use.
• Reaching a limit does not silently accept or delete unfinished work.
• Your model provider and connected infrastructure remain billed to your own accounts.

Models, skills and MCP connections

Portable setup profiles describe what an Assignment needs without copying credentials or private state.

1. 1

   Import

   Add a versioned profile that names model roles, skills, MCP servers and required capabilities.

2. 2

   Approve

   A Project owner approves the exact revision and content hash. Importing never starts work or installs software.

3. 3

   Check

   The harness reports its inventory. Jentra identifies missing requirements, incompatibility and version drift before launch.

4. 4

   Bind

   Use a Project default or an approved Journey- or Assignment-specific profile. The most specific binding wins.

Model roles include WORK, DECISION_ADVISER, INDEPENDENT_VERIFIER and FALLBACK. A model role configures execution; it does not grant authority.

Official MCP server

npx -y @jentra/mcp-server

Set JENTRA_API_URL and a scoped JENTRA_SESSION_TOKEN in your harness secret configuration. The stdio server exposes Project context, Assignment context, Change Review, People & Agents and canonical command submission.

Portable agent skill

npm pack @jentra/agent-skill

Extract the archive and point your harness at SKILL.md, or copy it into the harness's supported skill directory. The skill contains behaviour and safety guidance only; live state always comes from Jentra.

Use Jentra from the CLI

The CLI is useful from a terminal, IDE task or agent harness.

npm install --global @jentra/cli
jentra --version

Authentication

Set JENTRA_API_URL to the control-plane origin and provide a Better Auth bearer session using JENTRA_SESSION_TOKEN. Keep tokens in your shell or secret manager, never in source control.

Machine-readable errors include a code, message, retry class, remediation actions and correlation ID.

Run candidate-bound Checks locally

Local and self-hosted users can run project-defined build, test, lint, type-check and policy commands on their own machine. Cloudflare and hosted CI are not required.

1. 1

   Review the policy

   Inspect jentra.checks.json. Commands use an executable and argument array, not a shell string. Independent commands may run concurrently and dependsOn defines ordering.

2. 2

   Bind the candidate

   Supply the exact commit, tree or content hash being checked.

3. 3

   Run locally or in your CI

   Use jentra check local --candidate <hash>. Use jentra check init-ci --provider github or gitlab to create a reviewable starting workflow.

4. 4

   Attach the receipt

   Add --journey <id> --direction <revision-id> --upload when the result should appear in Change Review. Declared artifact files are bounded and represented by digest.

The direct runner terminates process trees on cancellation or timeout. Use a sandboxed eligible runner when network or stronger resource isolation is mandatory. The basic local runner fails closed when such isolation is required.

SDK and API

Use the public contracts, TypeScript SDK and HTTP API to build compatible clients and automation.

Core API areas

Projects and activity previews; Journeys and Assignments; participants and Worlds; contributions and verification; decisions and resolution; runtime placement and callbacks; setup profiles; memory and usage.

Connect a runtime host

A runtime host turns Jentra Assignments into work performed by Codex, Hermes or another compatible harness.

1. 1

   Register

   Advertise a reachable host, adapter, capabilities, capacity and an opaque authorisation reference.

2. 2

   Accept a manifest

   Validate the Assignment, World, capability grant, exact instruction package, alignment envelope, expiry and idempotency key.

3. 3

   Execute

   Resolve credentials from the host secret store and run inside the assigned World.

4. 4

   Report

   Send ordered heartbeats, checkpoints and one terminal result. Duplicate callbacks are safe; conflicting replays fail closed.

Compatible hosts must recover accepted work durably, honour cancellation, enforce capacity and refuse stale or capability-incompatible work. New hosts can advertise Jentra native-tool vocabulary versions, tool versions and bounded actions so Assignments remain portable across providers without assuming that two similarly named tools behave the same.

1. 1

   Initialise local state

   npx @jentra/community-runtime init

2. 2

   Start the runtime

   npx @jentra/community-runtime start, then open http://127.0.0.1:4317. Create a Project, start work and connect an existing local Git repository.

3. 3

   Open a World

   Create an isolated World backed by a real Git worktree. Commit there, propose the current commit and record an explicit accept or reject decision in Change Review.

4. 4

   Connect an agent

   Set JENTRA_API_URL=http://127.0.0.1:4317 and a local participant identity, then launch npx @jentra/mcp-server. Agents read the same direction, Worlds, coordination messages and review state shown in the browser.

The Community Runtime includes local Projects, Journeys, Git-backed Worlds, participants, shared coordination messages, current direction, append-only activity, versioned commands and contribution review. It does not silently merge or deploy. Managed execution, hosted identity, billing and large-scale scheduling remain outside this edition.

Read the source and contribute

The experimental self-hosted package contains the Jentra control plane, not a bundled model or agent. Your installation owns its accounts, coordination data, evidence and connected-provider credentials.

Security and privacy

Jentra separates account identity, agent execution and provider credentials.

• Better Auth owns application accounts and sessions; ordinary sign-in does not require Cloudflare Access.
• Credentials remain in approved secret systems and are referenced by opaque handles.
• World grants bind participant, repository or tool, capabilities and expiry.
• Cross-World and cross-account access is rejected server-side.
• Consequential callbacks require current alignment and valid service identity.
• Personal memory is private by default; shared memory requires explicit promotion and review.
• Account deletion purges private memory while preserving shared Journey integrity and audit history.

Read the privacy noticeRead the terms

Troubleshooting and recovery

Start with the symptom you can see. Jentra should preserve accepted state when an external service or runtime fails.

The verification email did not arrive

Check spam and the address you entered, then request a new message. Only the newest valid link may work. Local Docker does not require email verification.

Sign-in returns to the same page

Confirm cookies are enabled and that the installation origin matches its authentication URL and trusted origins. On self-hosted Cloudflare, verify BETTER_AUTH_URL and BETTER_AUTH_TRUSTED_ORIGINS.

Hosted signup is unavailable

Join the waitlist, use Local Docker, or deploy the signed release into your own Cloudflare account. The public page does not disclose remaining hosted capacity.

A repository import failed

Correct the remote, permission or runtime credential connector and retry. The current Project source remains intact until a replacement import completes.

A private repository is blocked

Configure an approved runtime credential connector that maps the opaque reference to a token already held by that runtime. Do not paste the token into Project context.

A World is still provisioning

Check the repository provider and runtime host status. Do not start a Run until the World is ready. A retry should reuse the same idempotent operation.

An agent stopped

Reconnect it or assign another compatible agent. The Journey retains accepted context and remaining work.

No agent accepts the Assignment

Check that a runtime host is online, has spare capacity and advertises every required capability, model role, skill and MCP connection.

A callback is stale

Refresh the Assignment alignment envelope before sending another consequential result. Do not replay the old result with a new identifier.

The goal changed while agents were working

Open Direction, propose the change, review affected Assignments, then apply the revision. Jentra marks affected work for continue, adapt, pause, reassign or supersede and requires refreshed context before consequential callbacks continue.

A provider is unavailable

Retry after recovery or choose another eligible runtime. Canonical Journey state remains in Jentra.

A limit was reached

Open Usage to see the allowance, reset and effect on active work. Unfinished work is not silently accepted or deleted.

Verification failed

Read the finding and its evidence, create successor work and verify that successor. Do not alter the failed record or ask the author to self-approve it.

A result is uncertain

Inspect its evidence, use Ask why or request an independent verifier. Do not accept uncertain work.

Composition found a conflict

Keep the conflict explicit, assign reconciliation work and verify the reconciled contribution before composing again.

Delivery did not happen

Verification and resolution do not merge, publish or deploy automatically. Check whether the separate delivery action is authorised and configured.

A credential may be exposed

Revoke it at the provider, replace the connection and inspect recent World activity. Do not include the credential in a report.

Local Docker will not start

Run npm run verify, confirm Docker Compose v2 is available, inspect npm run local:logs and keep the generated .env secret with the existing data volume.

A Cloudflare deployment fails

Confirm Wrangler is authenticated, required account services are available, migrations completed and BETTER_AUTH_SECRET is set. Then redeploy without deleting user-owned data.

An upgrade changed behaviour

Stop, preserve the database or Docker volume, read the release notes and apply the documented migrations. Experimental schema downgrades are not supported.

Glossary

Project

The long-lived home for related work, integrations and memory.

Journey

Consequential work whose direction and outcomes can evolve.

Assignment

A bounded piece of work given to a participant.

Participant

A person, agent or service acting under an explicit role.

World

An isolated or deliberately collaborative workspace.

Run

One execution attempt for an Assignment.

Contribution

A proposed result with claims, provenance and evidence.

Verification

An eligible independent check of a claim or contribution.

Decision

A recorded choice, its authority, reason and consequences.

Resolution

The selected composition of accepted contributions.

Memory

Governed knowledge Jentra may recall in an authorised scope.

Runtime host

The execution environment that runs a compatible agent harness.