canonical: https://jentic.com/apis/openbash.ai/openbash

# openbash

The openbash API runs shell commands against a hosted set of data programs through a single execution endpoint. Programs are commands rather than routes, so a pipeline of several of them piped through tools like jq and sort is one POST `/api/v1/exec` request, and the response carries the interleaved output, an exit_code, and a duration. Calls are stateless by default; opening a session keeps a working directory, environment, and /tmp across calls, and files in that scratch space can be read back over HTTP. The public program index endpoints list every program with its domain, tier, and help text, and mark which ones your account has enabled.

## For AI agents

Run shell commands and pipelines over openbash's hosted data programs, keep state in resumable sessions, and browse the program index with each program's help text.

## Scope

Does not host your own code, deploy containers, or provision virtual machines. Use for running openbash's hosted data programs as shell commands only.

## Capabilities

- Run one shell command or a piped pipeline of programs and read its output, exit_code, and duration_ms
- Stream command output as Server-Sent Events by setting stream to true
- Open or resume a session that keeps the working directory, environment, and /tmp across calls
- Read a file back from a session's /tmp scratch space, or from the bundle a submission froze
- Browse the program index filtered by domain, with tier, status, and whether your account has each program enabled
- Fetch one program's help text and example command before running it
- Poll the changelog to see which programs were added, newest first

## Use cases

### AI agent running data programs as shell pipelines

An AI agent working through Jentic searches for 'run a shell command on openbash', loads the exec operation, and sends one command line that pipes several programs together. The response returns the program output with an exit_code where 0 means results, 2 means not entitled, and 3 means no results found, so the agent can tell an empty answer from a missing entitlement. Your own Jentic One instance injects the bearer key at call time.

Example prompt: Call GET `/api/v1/programs/{slug}` to read a program's help, then POST `/api/v1/exec` with a command that pipes that program into jq and sort, and report output and exit_code

### Stateful multi-step research in a session

Some work needs files and environment to persist between steps. POST `/api/v1/sessions` returns a session_id, and commands sent to POST `/api/v1/sessions/{id}/exec` share that shell's working directory, environment, and /tmp. Drafts written in /tmp can be fetched with GET `/api/v1/sessions/{id}/tmp/{path}`, and DELETE `/api/v1/sessions/{id}` ends the shell when the work is finished.

Example prompt: Open a session with POST `/api/v1/sessions`, run two commands in it with POST `/api/v1/sessions/{id}/exec` that write and then transform a file in /tmp, read the result with GET `/api/v1/sessions/{id}/tmp/{path}`, then close it

### Program discovery before execution

The program index is public, so an agent can learn what exists before it holds a key. GET `/api/v1/programs` lists programs with slug, domain, tier (free, metered, or contract), and status, and accepts a domain filter. With a key, each entry shows whether your account has it enabled, and GET `/api/v1/key` returns the account and its programs_enabled list.

Example prompt: Call GET `/api/v1/programs` with domain=housing, then GET `/api/v1/key`, and return the programs in that domain that are enabled for this account

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/exec` | Run one shell command or pipeline |
| POST | `/api/v1/sessions` | Open or resume a session |
| POST | `/api/v1/sessions/{id}/exec` | Run a command inside a session |
| GET | `/api/v1/sessions/{id}/tmp/{path}` | Read a file from session scratch |
| GET | `/api/v1/programs` | List programs in the catalog |
| GET | `/api/v1/programs/{slug}` | Get one program with help text |
| GET | `/api/v1/key` | Show the key's account and enabled programs |

## Key resources

- **Programs** — Index entries with slug, domain, title, tier, status, enabled flag, help text, and an example command
- **Exec** — The single execution endpoint, returning output, exit_code, truncated, session_id, and duration_ms
- **Sessions** — Resumable shells that keep a working directory, environment, and /tmp across calls
- **Runs** — Frozen submission bundles listing the files a run produced

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 61 / 100
  - AI-Readiness & Agent Experience: 41 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/openbash.ai/openbash/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring openbash by hand means getting a key through the emailed-code exchange, sending it as a bearer token, tracking session ids across calls, and handling streamed output and the 1 MiB non-streaming cap. Through Jentic you install once, import openbash from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Rules bound openbash by operation: the command line travels in the POST `/api/v1/exec` body, so a rule decides whether your agent may execute at all, not which program it runs. You choose the operations it may call, so execution and DELETE `/api/v1/sessions/{id}` are not included unless you add them, leaving program index reads on their own.
- **Credential handling:** Your openbash key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a shell command' or 'list available programs', and Jentic returns the matching openbash operation with its input schema, including command, stream, and session_id, so the agent calls it directly.

## Related APIs

- **E2B** — Cloud sandboxes for running agent-generated code
- **GitHub** — Store scripts and results from shell runs in repositories
- **Judge0 CE API** — Sandboxed execution of source code in many languages

## FAQ

### What authentication does the openbash API use?

The openbash API uses a bearer token per its OpenAPI spec: send your key as Authorization: Bearer. Execution, session, run, and key endpoints require it. The program index reads (programs, a program's help, program surface reads, and the changelog) accept calls with or without a key, and POST `/api/auth/ssh` is public: call it with an email to receive a code, then again with the code as otp to receive a key. Through Jentic the key is stored by your own instance and attached at call time.

### Can I keep state between commands with the openbash API?

Yes. Calls to POST `/api/v1/exec` are stateless by default. Open a session with POST `/api/v1/sessions`, or pass resume with an earlier id, and run commands with POST `/api/v1/sessions/{id}/exec` to keep the working directory, environment, and /tmp. End it with DELETE `/api/v1/sessions/{id}`; simply stopping is a detach, and the session stays resumable under its id.

### What are the rate limits for the openbash API?

The OpenAPI spec does not state a numeric limit; it documents a 429 response when an account is rate limited, and a 504 when a command does not finish in time. Non-streaming output is capped at 1 MiB, flagged by the truncated field, so stream large output instead. See https://openbash.ai for current account limits.

### Is there an openbash MCP server?

You don't need an MCP server to give your agent openbash. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls the execution, session, and program index operations on demand without loading another server's tool definitions into its context.

### How do I run an openbash pipeline through Jentic?

Search Jentic for 'run a shell command on openbash', load the POST `/api/v1/exec` operation, and execute it with a command string such as a program piped into jq. Check exit_code in the response: a non-zero exit is a result, not an HTTP failure. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the openbash API?

Yes, at the operation level. For a read-only program index assistant, write a rule that allows GET `/api/v1/programs` and GET `/api/v1/programs/{slug}` only, and the agent can browse programs and their help but cannot execute anything or close sessions. If you allow POST `/api/v1/exec`, the command line travels in the request body, so the rule decides whether the agent may run commands, not which commands; which programs exist is set by your account's enablement.