sim-one-alpha

Troubleshooting

The packaged diagnostic and service commands are not available in the pre-release CLI. Verify behavior at the output level: inspect the launcher error, request /health, open sim-one, submit a prompt, and confirm the expected response or side effect.

Installation Problems

The packaged installer is not published. Do not execute mutable latest content through curl | sh. Release installation uses a version-pinned download and checksum verification as documented in Installation.

For a source build, compare prerequisites and commands with Installation.

Gateway Does Not Start

Confirm:

src/core/config/gorombo.config.json is valid JSON before a source build, or ~/.gorombo/sim-one-alpha/gorombo.config.json is valid JSON in a packaged installation;
gateway.port is an integer from 1 to 65535;
the port is not occupied by another service;
selected model cards have their required credentials;
installed runtime files are readable by the current user.

Restart the gateway through the process or service manager that launched it. Do not treat a running process or listening port as proof that the gateway is working. Request /health, then submit a real terminal prompt and confirm the orchestrator responds correctly.

Terminal Cannot Connect

Start the terminal interface with sim-one and preserve the exact connection error.

When connecting to a non-default gateway:

sim-one --port <number>
sim-one --base-url <url>

--base-url overrides --port. The current terminal client supports a loopback HTTP endpoint and does not send x-api-secret; it cannot connect directly to a non-loopback gateway protected by external API authentication. Use an SSH tunnel that exposes the remote gateway on a local loopback port.

Model Or Credential Failure

Read models.primary and optional models.backup from the active configuration file, then verify the matching credentials in the active secret environment.

For a source checkout, edit src/core/config/gorombo.config.json, rebuild to refresh .gorombo/sim-one-alpha/gorombo.config.json, and keep credentials in the checkout .env. A packaged installation will use ~/.gorombo/sim-one-alpha/gorombo.config.json and ~/.gorombo/.env.

Model family	Credentials
Ollama Cloud cards	`OLLAMA_API_KEY` or `OLLAMA_CLOUD_API_KEY`
Codex Brain	`CODEX_BRAIN_LOCAL_API_URL` and `CODEX_BRAIN_LOCAL_API_KEY`

The Codex Brain URL must include /v1. Remove an unused backup card when its provider is intentionally not configured. The current runtime validates backup metadata and credentials but does not automatically fail over from the primary card.

After changes, restart the gateway through its launcher and verify a real model response.

Session Cannot Be Resumed

List recent sessions inside the terminal:

/sessions

Resume by exact id or explicit name:

/resume <session-id-or-name>

or:

sim-one --session <session-id-or-name>

A session is available only to its owning connector, actor, and conversation. Duplicate explicit names are rejected rather than guessed.

Telegram Does Not Respond

Check:

TELEGRAM_BOT_TOKEN is present;
TELEGRAM_WEBHOOK_SECRET_TOKEN matches the configured webhook;
the stored Telegram DM policy is pairing, allowlist, or disabled;
the user has completed pairing or appears in the allow list;
group mention and user restrictions admit the message.

Use the authenticated local terminal session to inspect or approve pending pairings. Do not place bot tokens or webhook secrets into a chat prompt.

See Connectors And Pairing.

Capability Does Not Appear

List the capability:

sim-one skill list
sim-one tool list
sim-one worker list
sim-one mcp list

Confirm that it is enabled, restart the gateway through its launcher, and open a new terminal session to verify that the capability is attached.

Tools, workers, and MCP servers are disabled by default unless explicitly enabled. Name collisions and unsafe ids fail without changing the registry.

External API Returns `401` Or `503`

For non-loopback requests:

configure API_SECRET;
send it in the x-api-secret header;
do not rely on forwarded loopback addresses to bypass authentication.

401 means the supplied secret is wrong. 503 means external API authentication is not configured.

See HTTP API Reference.

Memory Or Retrieval Problems

Check that the runtime can read the configured databases and bundled retrieval assets. Source-build defaults are:

.gorombo/db/
.gorombo/vector/
~/.gorombo/db/capabilities.sqlite

The first two paths resolve from the checkout working directory; the capability store defaults to the user’s home directory. Packaged installs will keep their runtime data under ~/.gorombo/. Do not edit the databases directly. Restore related state from a consistent backup when recovery is required.

Logs And Diagnostics

The SIM-ONE terminal UI writes privacy-safe, rotating JSONL diagnostics to:

~/.gorombo/logs/sim-one-ratatui.jsonl

This TUI log is bounded and omits prompt text, responses, selected text, secrets, session names, and raw errors. For the gateway and workers, preserve stdout/stderr from the launcher or service manager and inspect the protected /api/telemetry/runs and /api/telemetry/runs/:runId endpoints. Use event categories, session ids, run ids, and timestamps to correlate failures across those surfaces.

Recovery Order

Use this order:

Preserve the exact terminal or launcher error.
Validate configuration and required credentials.
Restart through the launcher or service manager.
Request /health.
Reproduce from the local terminal with a real prompt.
Check connector, session, run, or telemetry identifiers.
Repair the installation only after preserving ~/.gorombo/ runtime data.

This site is open source. Improve this page.