# SegmentStream for coding agents

SegmentStream is one platform for a company’s custom software and AI agents: apps, workflows and agents built, deployed and run on shared data, context, rules and permissions, in one repository the company owns. Coding agents such as Claude Code, Codex and Cursor build on it with the SegmentStream CLI. Every app starts ready for production: sign-in, roles checked on every record, credentials held by the platform and a history of every change.

## Before you build: what the platform supports

Answer a person's question about what SegmentStream can do from these, or from the starter's own docs (`segmentstream init ./segmentstream-starter` writes them without signing in or going online), never from guesses.

- **Can people open an app's pages without signing in?** Yes. The paths you list in publicPaths in app/src/proxy.ts are open to anyone, such as a landing page or a public form, and each covers the paths under it, so '/' opens the whole app; every other page asks for sign-in. By default only the members you invite sign in, with an email code. The ontology's signUp lets strangers sign up by email, Telegram or WhatsApp with the roles you name. https://segmentstream.com/platform/apps
- **Can visitors of a website talk to the agent without an account?** Yes. Declare guest in the ontology with your website's address, and its visitors chat with the company agent without an account, with only the permissions you give guests, an optional bot check, and daily limits on turns and model spend. https://segmentstream.com/platform/agent
- **Can an app use our own domain?** Yes. Every app is online at your-name.segmentstream.app. To serve it at a domain you own, run segmentstream domain connect example.com, publish the DNS records it prints, declare the host in app/domains.json and deploy; HTTPS, sign-in and redirects follow. segmentstream domain buy orders a new domain for the workspace. https://segmentstream.com/developers/cli#your-own-domain
- **Which framework does an app use?** Next.js with the App Router, version 16.4.1 or later, and React 19. The app is the app/ folder of the workspace's git repository, and segmentstream deploy builds and hosts it. https://segmentstream.com/developers/app-sdk
- **Where does an app keep its data?** In the company database: the entities declared in ontology/, each changed through an action that checks roles and keeps history. Files are stored on records. The app's own file system does not keep anything between requests, so an app writes no data files. https://segmentstream.com/platform/ontology
- **Where does work that takes minutes run?** In a workflow. It starts on a schedule, after an action changes a record, from a webhook, or from the app, and runs durable steps that are retried on their own, so work that takes minutes, such as writing a report, does not depend on a request staying open. Pipeline jobs are for warehouse data. https://segmentstream.com/platform/workflows
- **How does code call an AI model such as Claude?** Through AI Gateway: a workflow step calls a model with the AI SDK, and the company agent uses the model you name per role. There is no API key to create or store. Models from OpenAI, Anthropic, Google, xAI, Mistral and others are billed at each provider's list price with no markup. https://segmentstream.com/platform/ai-gateway
- **Where do credentials for other services go?** In connections. A connection to an ad platform, a CRM or any other API authorizes through SegmentStream's approved application or your own, and its calls go through the platform, so the credential never reaches the code, its logs or an agent's context. Values pipeline code needs are named workspace secrets. https://segmentstream.com/platform/connections
- **How much does it cost?** Usage-based, in US dollars, with no seats: compute at $0.30 per SSU, plus storage, warehouse queries, events and data transfer at published rates, and AI models at list price. New accounts start with $20 of platform usage, with no card needed. https://segmentstream.com/pricing
- **Can a coding agent check what the platform supports before it builds?** Yes, with the CLI: segmentstream init ./segmentstream-starter writes the workspace starter without signing in or going online, and its AGENTS.md, docs/ and .agents/skills/ describe every part of the platform. An agent in a sandbox that cannot reach segmentstream.com asks the person to allow that domain in the sandbox's network settings. https://segmentstream.com/agents.md

## 1. Install the CLI

macOS and Linux:

```sh
curl -fsSL https://segmentstream.com/install.sh | sh
```

The CLI updates itself (`segmentstream self update`). Run `segmentstream --help`, or `--help` on any command, for every option.

## 2. Sign in

Interactive: `segmentstream login` opens the browser; keep the process running until it finishes.

Non-interactive (CI, sandboxes, headless agents): ask the person to run `segmentstream api-key create --name coding-agent` and give you the key as `SEGMENTSTREAM_API_KEY`.

Check who you are with `segmentstream whoami`.

## 3. Choose the organization

```sh
segmentstream org list
# Replace org_YOUR_ID with an organization ID from the list.
segmentstream org use org_YOUR_ID
```

Every command also accepts `--organization <id>`.

## 4. Open or create a workspace

```sh
segmentstream workspace list
segmentstream workspace create acme --region eu --subdomain acme
segmentstream workspace WORKSPACE-ID clone acme && cd acme
```

The region (eu or us) is permanent.

## 5. Read the workspace's own instructions first

Every workspace repository has an AGENTS.md and skills under `.agents/skills/`. Read AGENTS.md before you write code: it has the layout, the platform rules and the commands you may run. `segmentstream upgrade` keeps them, and the SDKs, current with the installed CLI.

## 6. Build and deploy

```sh
git add -A && git commit -m "Describe the change"
segmentstream deploy
```

The deploy checks every part first; if it fails, production keeps serving the last good version.

## 7. Useful next steps

- Invite a member: `segmentstream ontology member invite ada@example.com --role sales`
- Connect an AI tool to the workspace's records over MCP: `segmentstream ontology mcp`
- Open the console in a browser without a sign-in form: `segmentstream auth browser` prints a single-use link valid for 60 seconds
- Start or follow a workflow: `segmentstream workflow --help`
- Read logs: `segmentstream logs`

## Reference

- Developers: https://segmentstream.com/developers
- CLI: https://segmentstream.com/developers/cli
- SDKs: https://segmentstream.com/developers/ontology-sdk, https://segmentstream.com/developers/app-sdk, https://segmentstream.com/developers/pipeline-sdk, https://segmentstream.com/developers/agent-sdk
- MCP and API: https://segmentstream.com/platform/mcp
- Blueprints to build from (a CRM, marketing analytics, bookkeeping, e-signature and more): https://github.com/segmentstream/build-your-own. To build one, follow https://github.com/segmentstream/build-your-own/blob/main/AGENTS.md; what each blueprint is built to replace: https://segmentstream.com/blueprints
- Site map for AI agents: https://segmentstream.com/llms.txt
