Desired-state compute resources

curl -X POST \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/inference-services" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"himalaya-service",
    "model_alias":"himalaya-q8",
    "min_replicas":0,
    "max_replicas":2,
    "spec":{"region":"eu-central"}
  }'

The canonical organization route is /orgs/{org_id}/inference-services. The compatibility binding /inference-services remains available when org_id is supplied in the request body.

Review the price before applying a host

Send the intended request with dry_run: true to receive spec.compute_quote. Review its billing currency, exact allocated memory, hourly rate and next-lease hold. Submit the same request with dry_run: false and accepted_quote_id within five minutes. The console requires this confirmation. Existing EU API clients may omit the quote; technical core and pro sizes are not subscription offers.

Model calls and any separately accepted data policy are additional. Running hosts renew paid leases. See quotes, reservations and usage policy.

curl \
  "https://tarka.rest/control/v1/agent-host-templates" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"

# Upload secrets through the authenticated console handoff first.
# The bundle UUID is safe for the assistant to handle; secret values are not.
jq -n \
  --arg bundle "$TARKA_SECRET_BUNDLE_ID" \
  '{
    name: "research-agent",
    template_id: "openclaw",
    tier: "core",
    dry_run: true,
    secrets_bundle_id: $bundle,
    runtime: {primary_model_alias: "deepseek-v4.1-flash-eu"}
  }' |
curl -X POST \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/agent-hosts" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  --data @-

curl \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/agent-hosts/$AGENT_HOST_ID/configuration" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"

Secret values are empty in this response. A secret with preserve_existing: true can be carried into the next revision without returning its plaintext.

curl \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/agent-hosts/$AGENT_HOST_ID/gateways/signal/pairing" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"

curl -X DELETE \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/agent-hosts/$AGENT_HOST_ID" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"

Use the token owner's GitHub username and a classic PAT with read:packages, access to every referenced package, and organization SSO authorization when required. The username is not the repository or package owner. Your Tarka account token authenticates the Control API; the GitHub PAT is used only for GHCR pulls.

Named credentials and verified pulls

The console uses POST /control/v1/orgs/{org_id}/agent-host-registry-tests with the host name, a complete credentials array and every GHCR image with its Compose service. Each credential has a label, username, token and assigned services. To preserve a stored token, send its returned id and version and omit the token. Removing an entry removes that credential only after a successful test and apply.

Poll GET /control/v1/orgs/{org_id}/agent-host-registry-tests/{test_id}. When its status is succeeded, include registry_test_id in the complete host apply request. Do not combine it with github_registry_credentials. The proof expires after 30 minutes, binds to the exact service images and current credential version, and is consumed once by a successful apply. Dry runs do not consume it. Cancel queued or running tests with DELETE at the same test URL.

Configuration reads return registry_credentials containing IDs, labels, usernames, versions and service assignments only. Starting a credential test is a human action through the console or direct HTTP and is excluded from MCP. MCP can read test status and submit the verified test ID without receiving a PAT.

Compatible single-credential requests

import getpass, json, os, pathlib, urllib.request

payload = {
    "name": "private-agent",
    "compose_yaml": pathlib.Path("compose.yaml").read_text(),
    "github_registry_credentials": {
        "username": os.environ["GITHUB_USERNAME"],
        "token": getpass.getpass("GitHub classic PAT: "),
    },
}
url = "https://tarka.rest/control/v1/orgs/" + os.environ["TARKA_ORG_ID"] + "/agent-hosts"
request = urllib.request.Request(url, method="POST",
    data=json.dumps(payload).encode(), headers={
        "Authorization": "Bearer " + os.environ["TARKA_ACCOUNT_TOKEN"],
        "Content-Type": "application/json",
    })
payload["dry_run"] = True
request.data = json.dumps(payload).encode()
with urllib.request.urlopen(request, timeout=60) as response:
    preview = json.load(response)
quote = preview["spec"]["compute_quote"]
print(json.dumps(quote, indent=2))
if not quote["admission"]["available"] or input("Accept this price and create? [yes/no] ") != "yes":
    raise SystemExit("Not created")
payload.update(dry_run=False, accepted_quote_id=quote["id"])
request.data = json.dumps(payload).encode()
with urllib.request.urlopen(request, timeout=60) as response:
    host = json.load(response)
print(host["id"], host["status"])

The example reads compose.yaml and prompts for the PAT without echoing it. Do not print the request or put credentials in Compose, spec, source code, logs, or chat transcripts.

Preserve, replace, and remove credentials

Apply the same host name and the complete Compose definition on each update. Tarka checks GHCR access before saving; a failed check leaves credentials and the current revision unchanged.

• Preserve: omit github_registry_credentials. An empty object is not the preserve operation.
• Replace: supply both username and the new token.
• Remove: send {remove: true} after switching every GHCR image to anonymous access. Do not combine removal with a username or token.

{
  "github_registry_credentials": {
    "remove": true
  }
}

GET /control/v1/orgs/{org_id}/agent-hosts/{agent_host_id}/configuration returns only the saved username and configured status. The token is write-only, encrypted at rest, and never returned or included in revision history. The controller provides it only as an image-pull credential, never a container environment variable.

{
  "github_registry_access": {
    "username": "octocat",
    "configured": true
  }
}

Deleting a host removes its saved credentials. Removal does not revoke the PAT at GitHub or stop already running containers. Revoke the PAT at GitHub when required.

MCP

Connect your MCP client as described in MCP. Creating a host needs a connection with write access, provisioning:read provisioning:write. Set or change private GHCR credentials yourself through the console or direct HTTP; MCP rejects plaintext registry credentials. Omitted credentials preserve the host's existing pull access. Supply application secrets through a separate handoff, then pass its ID in the complete apply request and review the price before creation.

{
  "name": "tarka_create_agent_host",
  "arguments": {
    "org_id": "<organization UUID>",
    "name": "private-agent",
    "dry_run": true,
    "compose_yaml": "services:\n  agent:\n    image: ghcr.io/my-org/my-agent:v1\n",
    "secrets_bundle_id": "<uploaded secret handoff UUID>"
  }
}

Read back with tarka_get_agent_host_configuration and org_id/agent_host_id. Its github_registry_access contains the same redacted metadata. A read-only MCP grant cannot set, replace, or remove credentials.

Secrets from a file or the console

Prepare a handoff with POST /control/v1/orgs/{org_id}/agent-host-secret-bundles and the host's name. Open its console_url yourself to upload a .env file or a JSON object of string values. The local secret-file helper can upload directly from your terminal using your account token in the environment. Do not have the coding agent read the file or paste its contents into chat.

The assistant reads only key names and status, then submits secrets_bundle_id with the host request. The handoff expires after one hour and is consumed only by successful admission for the same organization, name and revision. A concurrent host update requires a new handoff. Direct HTTP clients can continue sending inline secrets.

Python SDK

SDK 0.2.0 adds AgentHostGitHubRegistryCredentials and the matching redacted response type. See the Python credential examples and installable release.

For the console workflow, see Private GitHub images.

Tarka registry images

Push your local build with a Tarka credential and reference registry.tarka.rest/orgs/<organization UUID>/<repository>. Agent Hosts accept tags and pin the resolved digest; jobs require an explicit digest. The resource and image must belong to the same organization. Pull authorization is automatic; omit github_registry_credentials for Tarka images.