Documentation — openbash

How to reach the openbash shell over HTTP, SSH and MCP: authentication, the exec call, sessions, the output contract and the exit codes.

Reaching the shell

A key authenticates every door. Over HTTP it is a bearer token on POST /api/v1/exec; over SSH the username is the key, so there is no registration step, no agent and no client configuration; over MCP it is the usual authorization, and the server exposes one bash tool.

POST /api/v1/sessions opens a session when state has to survive across calls — a working directory, an environment, files written to /tmp. Without one, each exec is independent.

curl -sS https://openbash.ai/api/v1/exec \
  -H "Authorization: Bearer $OPENBASH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ami rents --county sd"}'

• The OpenAPI specification
• llms.txt — orientation written for an agent, not a person
• How to reach each door, as pasteable strings

Exit codes are results, not HTTP errors

A command that exits 3 because it found nothing ran perfectly, and comes back in a 200 with exit_code 3. Only transport failures are HTTP errors.

0  results
1  usage error — the flag or argument was wrong
2  not entitled — the program exists, this key does not have it
3  no results found — the query was valid and matched nothing
4  upstream data failure — the source could not be read

Errors are the documentation

An unsupported flag names the flags that are supported; an unknown command names the near misses. Try something, read the failure, adapt. That path is designed to work, and it is the intended way for an agent to learn this surface.