Docs
Sign in Start building

Run Codex on MIOSA

~15 min TypeScript Python

What you’re building: Install the Codex CLI in a sandbox with streamed events.

Primitives you’ll use: Sandbox, Agent and harness

Agent prompt

Start with your coding agent

Choose how you will use it. The brief installs and runs the real tool on MIOSA, then shapes it for your team or your customers. Copy it into OSA, Claude Code, Codex, or Cursor.

Template coming soon

1 What are you building?

Leave it empty and your agent will propose 3 names, pick one, and use it for resources, the domain and branding.

3 Configure

Model
Scale
Extras

4 Your prompt

Reference tool

Codex, by OpenAI (https://openai.com/codex): OpenAI's coding agent.

How it works: Codex takes a task, works in an isolated environment with the repository, runs commands and tests, and returns changes for review; many tasks can run in parallel.

Key capabilities:

Delegate coding tasks to run in parallel

Edits files and runs tests in an isolated environment

Returns a reviewable change

Works from the CLI or the cloud

You will install and RUN the real Codex (Codex CLI from OpenAI; installs with an official install script or npm). Read its docs first: https://github.com/openai/codex. Every install command below comes from them; if the docs and this brief disagree, the docs win.

How it runs on MIOSA

Where it runs -> a MIOSA sandbox (an isolated Linux workspace)

State and files -> Keep the repo in /workspace; a persistent sandbox keeps it, and the `~/.codex` config, across pauses.

Model -> your own provider key, never a MIOSA platform key

MIOSA can also dispatch it as the built-in `codex` harness: runs, events, files and approvals come with it

Your customers -> one workspace each, isolated from each other

Goal

Install and run Codex on a MIOSA sandbox, so it can serve my customers. Each customer is isolated in its own workspace; I meter usage and bill them.

Product name: propose 3 product names, pick one, and use it for resource names, the domain and branding. Until you pick, <product-name> stands for it in the commands below.

Scale: a prototype.

Set up

npm i -g @miosa/cli

miosa login && miosa whoami

miosa api-key create <product-name>-key --preset agent

export MIOSA_API_KEY="msk_u_..."

miosa org

miosa connections add models # your own model provider key

Resources

Sandbox: the agent's isolated Linux workspace

miosa create <product-name>-task-1 --wait

Agents and harnesses: what a run can use

miosa agent harnesses

Auth and tenancy

Your organization is the platform; customers never get a MIOSA account, they sign into YOUR product. One workspace per customer, created as they onboard, isolates their machines, runs and data.

miosa workspace create <product-name>-customer-1

Tag every machine and run with the customer id in `metadata`, and never query across customers. Meter usage per customer with GET /api/v1/usage and set who pays with PUT /api/v1/bill-to (/docs/platform/usage-and-billing).

Install Codex

Run these inside the sandbox (for example `miosa exec <product-name>-task-1 -- bash -lc '<command>'`), in order. The commands are from the official docs.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Check: the install finishes without errors; the next sections configure and start it.

Configure

Authenticate with your own OpenAI key: export OPENAI_API_KEY="..." (or sign in with `codex`).

Model: OpenAI. Calls use my own provider key (OPENAI_API_KEY); MIOSA platform keys are never used.

export OPENAI_API_KEY="..." # set it in the process environment, or the Secrets API; never write it into files you commit

Run it

Start it and prove it works.

codex --version

Scripted, non-interactive use (what a product or a queue would call):

codex exec "summarise this repository and list the failing tests"

MIOSA also runs it natively. Dispatch a task and stream its events, files and approvals through MIOSA:

miosa prompt --sandbox <product-name>-task-1 --harness codex --model <openai-model-id> "summarise this repository"

Sessions: one chat per project or conversation, so the agent keeps its context. The first `miosa prompt` on a sandbox uses `--new-chat` (a chat id is printed); every later turn passes `--chat <chat-id>`. `--reuse chat` keeps one new machine per chat so files persist.

miosa run follow <run-id>

Check: a headless task completes and prints a result.

Persistence and access

Keep the repo in /workspace; a persistent sandbox keeps it, and the `~/.codex` config, across pauses.

Check: after the machine pauses and resumes, the tool starts again with its state intact.

Make it a product

Run each customer task in that customer's workspace with `miosa prompt --harness codex` and stream the events into your own UI.

Limits and costs

Pin the version you tested and update deliberately; these tools change quickly.

Give the tool only the credentials it needs, as secrets, not baked into files.

Prototype: keep it to one machine at the default size, skip replicas and custom hostnames you do not need, and delete everything when you are done.

Acceptance checks

Codex runs on a MIOSA sandbox and answers a real task.

State survives a pause and resume.

Each customer has its own workspace and its own instance; nothing is shared between them.

Everything it created can be deleted with nothing left running.

What your choices added

  • Build a product. a workspace per customer, per-customer metering and bill-to
  • Agent suggests a name. proposes 3 product names and picks one; commands use <product-name>
  • Model: OpenAI. your own provider key
  • Prototype. one small machine, no extras, easy to delete

What you're building

OpenAI's coding agent Modelled on Codex, by OpenAI.

Codex takes a task, works in an isolated environment with the repository, runs commands and tests, and returns changes for review; many tasks can run in parallel.

Primitives you'll use: Sandbox · Agent and harness

  • Delegate coding tasks to run in parallel
  • Edits files and runs tests in an isolated environment
  • Returns a reviewable change
  • Works from the CLI or the cloud

You install and run the real Codex on MIOSA. Read the official docs first: github.com/openai/codex. Every install command below comes from them; if the docs and this guide disagree, the docs win. Codex is Codex CLI from OpenAI; installs with an official install script or npm.

What you need on MIOSA

Each row is one thing to create before you start. The number matches the step that uses it.

  1. Organization and API key Scopes every call; a workspace key is all a worker needs. miosa api-key create app-key --preset agent Docs
  2. Sandbox The isolated Linux workspace the agent writes code and runs commands in. miosa create app-box --template nextjs --wait Docs
  3. A workspace per customer Isolates each customer’s machines, deployments, and data as they onboard. miosa workspace create customer-1 Docs
  4. Branding and white-label Your name and slug on previews, deployments, and the desktop; customers never see MIOSA. miosa org Docs
  5. Usage metering and bill-to Usage per customer, and which account pays for new machines. miosa org bill Docs
  6. Agent and harness Turns a prompt into work: pick the harness and model a run uses. miosa agent harnesses Docs

Architecture

How it runs on MIOSA

Where it runs -> a MIOSA sandbox (an isolated Linux workspace)

State and files -> Keep the repo in /workspace; a persistent sandbox keeps it, and the `~/.codex` config, across pauses.

Model -> your own provider key, never a MIOSA platform key

MIOSA can also dispatch it as the built-in `codex` harness: runs, events, files and approvals come with it

Your customers -> one workspace each, isolated from each other

Auth and tenancy

Your organization is the platform; customers never get a MIOSA account, they sign into YOUR product. One workspace per customer, created as they onboard, isolates their machines, runs and data.

miosa workspace create codex-customer-1

Tag every machine and run with the customer id in `metadata`, and never query across customers. Meter usage per customer with GET /api/v1/usage and set who pays with PUT /api/v1/bill-to (/docs/platform/usage-and-billing).

Install Codex

Run these inside the sandbox (for example `miosa exec codex-task-1 -- bash -lc '<command>'`), in order. The commands are from the official docs.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Check: the install finishes without errors; the next sections configure and start it.

Configure

Authenticate with your own OpenAI key: export OPENAI_API_KEY="..." (or sign in with `codex`).

Model: OpenAI. Calls use my own provider key (OPENAI_API_KEY); MIOSA platform keys are never used.

export OPENAI_API_KEY="..."   # set it in the process environment, or the Secrets API; never write it into files you commit

Run it

Start it and prove it works.

codex --version

Scripted, non-interactive use (what a product or a queue would call):

codex exec "summarise this repository and list the failing tests"

MIOSA also runs it natively. Dispatch a task and stream its events, files and approvals through MIOSA:

miosa prompt --sandbox codex-task-1 --harness codex --model <openai-model-id> "summarise this repository"

Sessions: one chat per project or conversation, so the agent keeps its context. The first `miosa prompt` on a sandbox uses `--new-chat` (a chat id is printed); every later turn passes `--chat <chat-id>`. `--reuse chat` keeps one new machine per chat so files persist.

miosa run follow <run-id>

Check: a headless task completes and prints a result.

Persistence and access

Keep the repo in /workspace; a persistent sandbox keeps it, and the `~/.codex` config, across pauses.

Check: after the machine pauses and resumes, the tool starts again with its state intact.

Make it a product

Run each customer task in that customer's workspace with `miosa prompt --harness codex` and stream the events into your own UI.

Limits and costs

Pin the version you tested and update deliberately; these tools change quickly.

Give the tool only the credentials it needs, as secrets, not baked into files.

Prototype: keep it to one machine at the default size, skip replicas and custom hostnames you do not need, and delete everything when you are done.

Acceptance checks

Codex runs on a MIOSA sandbox and answers a real task.

State survives a pause and resume.

Each customer has its own workspace and its own instance; nothing is shared between them.

Everything it created can be deleted with nothing left running.

Next steps

Was this page helpful?