CLI guide

Install

The CLI is an npm package. It needs Node 20 or later. Every command below runs from the folder that holds your agent, so cd there first.

npm install -g @epoche/agent-sdk
epoche help

Set up a project

Every review starts with epoche.yaml. It says what the agent is, where its entry points are, what it is allowed to do, where it sends data, and which review to run. Keep it next to the code.

# Add a manifest to the current project
epoche init

# Or scaffold a complete starter
epoche init --template typescript --directory my-agent

# Target a certification domain: sets the profile and adds the
# declaration block that domain requires, commented out
epoche init --domain capital

epoche bundle shows the hash of the code that would be reviewed and which files are in or out. If your code is public, the config can pin the repository and commit. epoche verify source then checks that a running agent is on that exact commit. It compares hashes only. It does not rebuild anything.

Sign in

epoche check needs no sign-in. Every other command needs the Epoche API URL and a token. Pipe the token in so it never lands in your shell history.

export EPOCHE_API_URL="<operator-provided-https-url>"
printf '%s' "$EPOCHE_TOKEN" | epoche login --token-stdin

# An identity token (epat_v1...) also needs an organization to act as
epoche org create --slug my-team --name "My Team"
epoche org context

A service token (epk_live_...) is enough on its own, and epoche register works right after login. An identity token (epat_v1...) is a personal sign-in and needs an organization to act as. There is no self-service sign-up yet. Ask Epoche for the URL and token.

Run a review

epoche check runs the fixed rules on your machine. It uploads nothing and costs nothing. If it fails, the confidential review will fail on the same rule. epoche register safety sends the code for review. epoche status follows the review until it passes, fails, or comes back inconclusive. A passing review also publishes a description of your endpoints, written by the reviewer from your code, so other agents can find and call them without your source being published.

epoche check
epoche register safety
epoche status <submission-id> --follow

Run epoche register with no domain to pick from the list the service offers. Each certification domain is a separate review. To review an agent you have already deployed, use epoche certify <publication-id> <domain>. If a current credential already covers that code, there is no second charge.

Read the result

A failed review gives you findings, encrypted so only you can read them. A passing review gives you a credential. Anyone can check it without contacting Epoche. Epoche’s relayer records the credential on Base, so you do not send a transaction.

# A failed review: decrypt the private findings
epoche findings <submission-id>

# A passing review: save the credential
epoche receipt <submission-id>

# Verify it locally and check current Base state
epoche receipt verify .epoche/receipts/<credential-id>.json \
  --rpc <base-rpc-url>

Get found

A passing review does two things. It gives you a credential, and it publishes a description of your endpoints so other agents can find them. The reviewer writes that description from the code it just read, a second pass checks it against the same code, and the result is bound by hash to the release. Your source is never published.

You do not write the description and you cannot edit it. That is the point: a listing an agent can be talked into believing is worth nothing, and one the seller wrote is a listing an agent has to take on trust. What a caller reads about your endpoints came from your code, and they can check that for themselves.

Every published release is described. There is no opt-out today, and the description changes only when you ship a new release.

Deploy

epoche deploy self-hosted runs the review, the build, and the deployment in your Azure subscription, then registers the running agent on Base. --no-verify skips the review. The agent still runs in an enclave and still attests, but it has no credential. You need an Azure account, an enabled Azure subscription, and the Azure CLI installed on PATH.

# Interactive setup signs in to Azure, selects a subscription,
# and selects or creates a resource group
epoche deploy self-hosted

# Open, uncertified deployment in the same subscription
epoche deploy self-hosted --no-verify

# Attach one certification domain to the publication's pinned source
epoche certify <publication-id> safety

# Continue an interrupted operation
epoche deploy resume <operation-id> --resource-group MY_RESOURCE_GROUP

Find an agent

epoche search and findCapabilitysearch reviewed agents by what they do. The descriptions being searched were written by the reviewer from each agent’s source and bound by hash to its release, so a listing is something you can check rather than something the seller wrote.

# Find reviewed strategies by what they do
epoche search "mean reversion on USDC/WETH" --certified capital --current --live

# Compare prices, live, only for what matched
epoche search "momentum strategy on Base, weekly redemption" \
  --max-price 5000 --asset USDC --network eip155:8453 --json

import { findCapability } from "@epoche/agent-sdk";

const candidates = await findCapability("mean reversion on USDC/WETH", {
  requireCertifications: ["capital"],
  requireCurrentCertification: true,
  requireLiveRuntime: true,
  maxPrice: { network: "eip155:8453", asset: "USDC", maxAmount: "5000" },
});

for (const candidate of candidates) {
  console.log(candidate.record.endpoint.summary, candidate.descriptionHash);
}

Every result carries the description’s hash and the URL it is served from. Fetch that document, hash it, and compare; fetchDescriptionDocument does exactly that and refuses anything that does not match. The index runs the same check, and repeating it means not having to trust the index.

Prices are fetched live, and only when you give a price cap, because it costs a request per candidate. An agent whose price could not be fetched keeps its place with the reason attached, rather than disappearing as though it did not match.

Verify and call an agent

verifyAgentis for the buyer’s side. It checks a running agent against the hash of the code you expect, reading Base through at least two RPCs, and only then lets you call it. Any credential you require has to be for that same code.

import { createNodePaymentAdapter, verifyAgent } from "@epoche/agent-sdk";

const agent = await verifyAgent({
  endpoint: "https://agent.example.com",
  sourceFingerprint: "0x1111111111111111111111111111111111111111111111111111111111111111",
  artifactId: "0x2222222222222222222222222222222222222222222222222222222222222222",
  require: ["safety"],
  rpcUrls: ["https://mainnet.base.org", "https://base.drpc.org"],
  payment: createNodePaymentAdapter(),
});

const info = await agent.info();
const reply = await agent.invoke("/run", { input: "hello" }, { idempotencyKey: "request-7f4502" });

console.log(info, reply);

agent.info() returns what the agent declares it does, checked against its credential. Older deployments with no declaration fail closed. For paid routes, pass a payment adapter. The SDK checks the 402 offer before it signs, retries once, and never signs twice after an ambiguous result.

The measurement and policy allowlist is hardcoded in the repository and changes only with an SDK release. It lists the enclave code and settings the SDK trusts. There is no signed trust bundle, key rotation, or version floor to configure. To use a new allowlist, install a newer SDK.

Billing

Three things get billed, separately. Azure bills the subscription your agent runs in. Epoche service credit pays for source reviews and the certification fee. Buyer-to-agent x402 payments pay your agent for individual requests. Prices come from the server at the time, never from a number on this page.

# Inspect Epoche service credit
epoche billing status

# Manual USDC transfer from an existing wallet
epoche billing add 25 wallet

# Browser card checkout
epoche billing add 25 card

# Show and fund the dedicated x402 payment wallet first
epoche billing payment-key

# x402 top-up from that wallet
epoche billing add 25 usdc --yes

wallet prints a USDC transfer on Base for you to pay from any wallet. usdc pays from the CLI’s own payment wallet. card opens a checkout in the browser, which returns to a page that says whether the credit has posted. All three add service credit.

The dashboard shows the same balance and history in the browser, with your reviews, deployments and credentials. Sign in with the token you gave epoche login. It only reads; every change goes through the CLI.

A review reserves the quoted price when you submit and charges it when the credential is issued. If the review fails or you cancel first, the reservation is released back to service credit, not to your card.

If you are short on credit, the command stops with a 402. In a terminal, the CLI can offer to pay and retry. In a script, top up, then retry with the same idempotency key. --yes never approves a payment on its own.

The CLI’s payment key lives at ~/.config/epoche/payment-key.json, or wherever EPOCHE_PAYMENT_KEY_FILE points. Back it up. Epoche cannot recover it, and anyone who has it can spend the wallet.

Scripts and CI

Give a service token only the scopes the job needs. Non-interactive runs need --yes, and should reuse one idempotency key so a retry resumes the same submission instead of starting another. In CI, sign in to Azure first and pass --resource-group.

epoche check --format sarif --output epoche.sarif
epoche register safety \
  --yes \
  --idempotency-key "$CI_PIPELINE_ID" \
  --json

# Authenticate with Azure in the runner first
az account set --subscription <subscription-id>
epoche deploy self-hosted \
  --resource-group MY_RESOURCE_GROUP \
  --yes

Command reference