GitHub - satmihir/codex-artifact-server: Local API to use codex programmatically for text and images · GitHub
/" data-turbo-transient="true" />
Skip to content
Search/
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
satmihir
codex-artifact-server
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>6 Commits<br>6 Commits
.github/workflows
.github/workflows
src
src
tests
tests
.env.example
.env.example
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
openapi.yaml
openapi.yaml
package-lock.json
package-lock.json
package.json
package.json
View all files
Repository files navigation
Codex Artifact Server
A standalone, local HTTP service that turns Codex SDK runs into synchronous text<br>responses and durable image artifacts. The directory is self-contained: it does<br>not import application code or inspect the parent repository.
The service is intended for trusted local applications. It binds to<br>127.0.0.1 by default, requires a bearer token, disables network access and web<br>search for Codex threads, and gives every image job an isolated temporary<br>working directory.
Install and run
Requires Node.js 22.13 or newer, and a working local Codex CLI installation.
Run the published package without installing it:
CODEX_ARTIFACT_TOKEN="replace-me" npx codex-artifact-server
Install it as a command instead:
npm install -g codex-artifact-server<br>CODEX_ARTIFACT_TOKEN="replace-me" codex-artifact-server
Use it as a dependency of another local project:
npm install codex-artifact-server
To work on the source, clone the repository and run it from there:
git clone https://github.com/satmihir/codex-artifact-server.git<br>cd codex-artifact-server<br>npm install<br>CODEX_ARTIFACT_TOKEN="replace-me" npm start
Alternatively, copy .env.example into your process manager's environment;<br>the server deliberately does not load parent-project environment files.
Codex uses the local machine's existing Codex authentication. The server does<br>not accept or require an OpenAI API key. This means every request it serves is<br>authenticated as your own Codex/ChatGPT account — please read Account terms and<br>intended use before running it.
Configuration:
Variable<br>Default<br>Purpose
CODEX_ARTIFACT_TOKEN<br>required<br>Bearer token
CODEX_ARTIFACT_HOST<br>127.0.0.1<br>Listen address
CODEX_ARTIFACT_PORT<br>4319<br>Listen port
CODEX_ARTIFACT_MODEL<br>account default<br>Optional Codex model
CODEX_ARTIFACT_CONCURRENCY<br>Concurrent image jobs, 1–16
CODEX_ARTIFACT_JOBS_DIR<br>OS temporary directory<br>Durable job files
CODEX_ARTIFACT_TTL_MS<br>24 hours<br>Terminal-job retention
CODEX_ARTIFACT_MAX_REQUEST_BYTES<br>96 MB<br>Maximum multipart request
See openapi.yaml for the complete API contract.
Text response
curl http://127.0.0.1:4319/v1/text \<br>-H "Authorization: Bearer $CODEX_ARTIFACT_TOKEN" \<br>-H "Content-Type: application/json" \<br>-d '{"prompt":"Return exactly: hello"}'
An optional responseSchema JSON Schema requests a structured final response.
Image artifact
curl http://127.0.0.1:4319/v1/images \<br>-H "Authorization: Bearer $CODEX_ARTIFACT_TOKEN" \<br>-F 'id=my-image-1' \<br>-F 'aspectRatio=3:4' \<br>-F 'prompt=A natural-light studio portrait' \<br>-F 'image=@reference.jpg'
The server returns 202 Accepted. Poll the returned job URL:
curl http://127.0.0.1:4319/v1/jobs/my-image-1 \<br>-H "Authorization: Bearer $CODEX_ARTIFACT_TOKEN"
Download completed bytes:
curl http://127.0.0.1:4319/v1/jobs/my-image-1/result \<br>-H "Authorization: Bearer $CODEX_ARTIFACT_TOKEN" \<br>--output result.png
After safely storing the bytes, acknowledge the job and immediately remove its<br>prompt, uploaded images, metadata, and result:
curl -X DELETE http://127.0.0.1:4319/v1/jobs/my-image-1 \<br>-H "Authorization: Bearer $CODEX_ARTIFACT_TOKEN"
If a client does not acknowledge a terminal job, garbage collection removes it<br>after its expiresAt time. Reading a result extends that expiry so an interrupted<br>download can be retried safely.
Account terms and intended use
This server does not use an OpenAI API key. It drives the Codex CLI and SDK<br>already installed on the machine, so every request it serves runs as your<br>Codex/ChatGPT account and consumes that account's entitlements.
Please take that seriously rather than as boilerplate. Putting an HTTP interface<br>in front of those credentials turns a personal, interactive subscription into a<br>programmatic API, which is not what a consumer plan is sold as. Depending on how<br>it is deployed, that can breach the terms governing your OpenAI account.
Use it as a local convenience for yourself, on your own machine. Do not:
expose it to other people, a...