# PromptOn documentation

PromptOn manages the prompts and model configuration used by your application. Each **prompt** has a deployed revision per **environment**: an immutable prompt version, model, parameters, and provider options. You can compare candidates, deploy them, and roll back without changing application code.

Your application fetches configuration when it needs a prompt, uses SDK-rendered content and runtime configuration to prepare the provider request, calls the provider using its own credentials, and reports the result as a log. PromptOn does not proxy the model call. A valid cached prompt can keep serving during a configuration outage; a cold lookup with no usable cache can fail. See [SDK config fetch](/sdk-config-fetch) for the one-second fetch budget and fallback rules.

**Chat** prompts manage instructions and examples; your application combines them with conversation history and current input. **Decision** prompts prepare native state and questions for a compatible model. Chat tools describe callable functions; the application owns their execution.

## Choose a starting point

| Your task | Start here |
|---|---|
| Learn the product and edit prompts in the web app | [Concepts](/concepts), then [Working with prompts](/workflows) |
| Connect an application manually | [Quickstart](/quickstart) |
| Have a coding agent connect an application | The setup prompt below, then [Agent setup guide](/agent) |
| Implement or debug an integration | [SDK guide](/sdks), [SDK config fetch](/sdk-config-fetch), and [Troubleshooting](/troubleshooting) |

## Two ways in

### Use a coding agent

Paste this into a coding agent running in your application codebase. It reads the PromptOn setup skill from the app host. The flow checks the fit, chooses the project's lowest active nonproduction environment from its pipeline order, provisions prompts there, creates ten synthetic sample logs per prompt in the same environment, shows the prompts and Logs pages for review, and waits for approval before migrating application code. After approval, setup/dev verification keeps using that recorded environment. Production rollout requires a separate request.

```text
Use the PromptOn setup skill:
https://app.prompton.ai/docs/skills/prompton-setup/SKILL.md

Explain what PromptOn is and how it works.
Check whether it's a good fit for this codebase.
If it is, propose a plan to migrate this project to PromptOn.
Proceed with the migration only after I explicitly approve the plan.
```

The hosted PromptOn setup skill is the short entry point. If your agent supports project-local skills, you may copy the hosted Markdown into the agent's skill directory as `prompton-setup`; otherwise follow it directly. The [agent setup guide](/agent) keeps the common flow short and points the agent to the current stage only.

### Or do it by hand

The [quickstart](/quickstart) walks through a nonproduction deployment, a rendered request, and a synthetic monitoring log using the CLI and curl. The [web app guide](/workflows) explains editing, Arena, deployments, Logs, and Evals at [the app](https://app.prompton.ai).

## Signing in for the first time

Sign-up and sign-in are the same step. There are no passwords.

1. Install [CLI 0.8.0](/cli#install) from its GitHub release.
2. Run `prompton login --host https://app.prompton.ai`. The CLI prints a link of the form `https://app.prompton.ai/device?code=H4KP-T7WR` together with the code, opens it in your browser, and waits.
3. Open the link if the browser did not open by itself.
4. Sign in with your email address. PromptOn emails you a 6-digit code; type it into the same page. A new address becomes an account, with its own personal organization, the moment its code is accepted.
5. The browser lands back on the device page showing the CLI's name and code. Press **Approve**.
6. The CLI prints `Logged in as you@example.com` and stores a session token in `~/.config/prompton/config.json`. The session does not expire; revoke it with `prompton logout` or from **Logged-in devices** on `https://app.prompton.ai/account`.

## Pages

| Page | What it covers |
|---|---|
| [Concepts](/concepts) | Organizations, projects, environments, prompts and versions, deployments as pins, models, API keys, monitoring logs, CLI sessions |
| [Working with prompts](/workflows) | The Editor, tools, Arena simulations, deployment review, Logs, and Evals |
| [Quickstart](/quickstart) | Sign in, provision a project with the CLI, fill a prompt with curl, send one log, see it in the app |
| [SDK](/sdks) | Source-pinned SDK installs and per-language request-contract readiness |
| ↳ [SDK HTTP API reference](/api) | The endpoints SDKs call with an SDK key: per-prompt config, full prompt exports, rendered prompts, logs |
| ↳ [SDK config fetch](/sdk-config-fetch) | The demand-driven per-prompt cache, timeout, rate-limit, fallback, and Node async migration contract |
| [CLI](/cli) | Installation, login, configuration precedence, every command, `--json`, exit codes, `--idempotent` |
| ↳ [CLI HTTP API reference](/management-api) | The endpoints the CLI calls with a session token: device login, organizations, and provisioning |
| [Agent setup guide](/agent) | The short setup flow and stage map for coding agents |
| [Setup provisioning](/setup-provisioning) | Repository inventory, CLI login, scope, environments, prompts, models, deployments, SDK keys |
| [Setup samples](/setup-samples) | Ten synthetic setup logs per prompt, sample accounting, review links |
| [Setup migration](/setup-migration) | Approval, review artifacts, application-code migration, verification, handoff |
| [Tools and traces](/tools-and-traces) | Tool definitions, app-owned history, actual tool events, completion evidence |
| [Security](/security) | Sign-in, credential boundaries, stored content, encryption, and cache behavior |
| [Troubleshooting](/troubleshooting) | Missing deployments, stale config, auth errors, request mismatches, and missing logs |

## SDKs

Official SDKs are available for eight languages as **GitHub source releases**. Use the versioned Git or source installation instructions in the [SDK guide](/sdks), then read only the selected language's versioned README. Package names below identify the libraries; they are not instructions to install an unverified package from a registry.

| Language | Package | Repository |
|---|---|---|
| Python | `prompton-sdk`, `import prompton` | [prompton-python](https://github.com/polimo-dev/prompton-python) |
| Node.js / TypeScript | `prompton-sdk` | [prompton-nodejs](https://github.com/polimo-dev/prompton-nodejs) |
| Go | `github.com/polimo-dev/prompton-go` | [prompton-go](https://github.com/polimo-dev/prompton-go) |
| Ruby | `prompton-sdk`, `require "prompton"` | [prompton-ruby](https://github.com/polimo-dev/prompton-ruby) |
| Java | `dev.polimo:prompton-sdk`, package `dev.polimo.prompton` | [prompton-java](https://github.com/polimo-dev/prompton-java) |
| Kotlin | `dev.polimo:prompton-sdk`, package `dev.polimo.prompton` | [prompton-kotlin](https://github.com/polimo-dev/prompton-kotlin) |
| Rust | crate `prompton-sdk`, `use prompton::…` | [prompton-rust](https://github.com/polimo-dev/prompton-rust) |
| Elixir | `prompton_sdk`, module `PromptOnSDK` | [prompton-elixir](https://github.com/polimo-dev/prompton-elixir) |

All eight implement the same cache and logging contract: no startup or idle polling, demand-driven per-prompt config fetch, a 10-second per-prompt freshness window and attempt gate, a 1-second fetch budget with no retries, same-prompt in-flight request sharing, fallback to the last valid prompt config even when expired, local prompt rendering, pinned runtime metadata, and batched logs. Request-helper APIs differ by language; use the [SDK guide](/sdks) and the installed SDK's source to check support. They never call the model provider. See [SDK config fetch](/sdk-config-fetch) for the exact cache behavior. For another language, use the [SDK HTTP API reference](/api) and [SDK config fetch](/sdk-config-fetch) to implement and verify the same contract.

## Read as Markdown

Every page has a `.md` URL, such as [agent.md](/agent.md). Extensionless URLs also return Markdown unless the request accepts `text/html`. [llms.txt](/llms.txt) lists the complete set of pages for agents and retrieval tools. Use the hosted setup skill to start an integration and the reference pages to resolve detailed behavior.

## Hosted service and public source

PromptOn is available as a [hosted service](https://app.prompton.ai). Self-hosting is not supported. The [CLI](https://github.com/polimo-dev/prompton-cli) and the eight SDKs listed above are open source under Apache 2.0, with their source available under [polimo-dev](https://github.com/polimo-dev).