Find the answer. Configure with confidence.

You need Node.js 22.19 or newer, npm, and an OpenRouter API key. Google OAuth, PostgreSQL, MCP, OpenShell, and live ads are optional for local development.

git clone https://github.com/tententgc/freeads-coder.git
cd freeads-coder
npm ci
cp .env.example .env.local
openssl rand -base64 32

NEXT_PUBLIC_APP_URL=http://localhost:3000
AUTH_URL=http://localhost:3000
NEXTAUTH_URL=http://localhost:3000
AUTH_TRUST_HOST=true
AUTH_SECRET=replace-with-the-generated-secret
OPENROUTER_API_KEY=replace-with-your-openrouter-key

npm run dev
curl http://localhost:3000/api/health

1. Select Start coding and sign in.
2. Choose a model from the model menu. GLM 5.3 Flash is the default for broad coding and multimodal work.
3. Describe the result you need, the relevant framework or files, behavior that must remain unchanged, and how the answer should be verified.
4. Open Settings to control reasoning, response language, response detail, built-in tools, custom tools, MCP, internet skills, and the isolated workspace.
5. Send the prompt. Tool calls, reasoning activity, the actual responding model, token use, and estimated cost appear in the response.
6. Use Stop to cancel upstream generation. A stopped response can be continued without repeating the completed part.

Outcome: Add a streamed Next.js route for this feature.
Context: Next.js 16 App Router, TypeScript, and the attached files.
Keep: Authentication and the existing NDJSON event contract.
Verify: Run typecheck, the focused tests, and the production build.
Report: Files changed, evidence, and anything that still needs operator setup.

The user selects the model in the chat header or Settings. Model fallback can be disabled when an exact route is required. Ox can infer a General, Build, Debug, Review, Tests, or Architecture working method, or the user can pin one method. Pi runs the model and tool loop and reports the model that actually completed the turn.

MiniMax M3 Free is the final configured fallback. A fallback is considered only when it supports every required input type. A model is not replayed after a workspace tool has changed or inspected files, because repeating side effects on another model would be unsafe.

OPENROUTER_DEFAULT_MODEL=z-ai/glm-5.3-flash
OX_MAX_REQUEST_COST_USD=0.01
OX_MAX_OUTPUT_TOKENS=4096
OX_MAX_INPUT_PRICE_PER_MILLION=0.25
OX_MAX_OUTPUT_PRICE_PER_MILLION=1
OX_MAX_AGENT_TURNS=8

• Model settings offer Pi reasoning levels from Off through Max, model fallback, zero to two provider retries, and response language. The same reasoning effort selector is available directly in the composer for quick per-task changes.
• Agent working method can stay on Auto or be fixed to General, Build, Debug, Review, Tests, or Architecture.
• Custom instructions are stored in this browser, capped at 2,000 characters, and applied as user-level preferences.
• Context compaction can be disabled or enabled. Maximum agent turns can be set from 2 to 12, subject to the server's lower operator ceiling.
• Up to eight prompt templates can be saved in this browser and inserted from the composer.
• Response language supports automatic selection, English, Thai, Japanese, Korean, Chinese, Spanish, French, and German.
• Response style can be concise, balanced, or detailed.
• Automatic tools can be disabled for an advisory-only turn, and each built-in tool can be switched independently.
• Appearance supports a clean white Light default, System and Dark alternatives, comfortable or compact density, and optional safe agent-activity details.
• New chat resets the active conversation but does not delete older history.
• Clear history removes local history and requests deletion of the signed-in user's cloud records when cloud storage is active.

With DATABASE_URL, completed chats synchronize to PostgreSQL and can appear for the same account on other devices. Without it, each browser keeps its own local storage. Local and production histories are separate unless both environments intentionally use the same database.

When context compaction is enabled, older messages become a bounded server-generated summary while recent messages stay verbatim. The full visible conversation remains in chat history. Disabling compaction sends the visible conversation until the normal request-size and provider-context limits are reached.

Remote attachments must use public HTTPS URLs without embedded credentials. Ox rejects local, private, link-local, reserved, and credential-bearing destinations. GLM 5.3 Flash supports every listed input. OpenRouter Free supports image and PDF but not video. Qwen3 Coder Next and GLM 5.2 Free accept text and PDF.

Each built-in tool is independently switchable in Settings, with a separate master switch for all automatic tool use. Tool activity is visible in the response. External results are treated as untrusted data and cannot replace platform or system instructions.

• Open Settings, choose Capabilities, then select + Tool or + Skill.
• A custom tool needs a name, description, public HTTPS endpoint, and GET or POST method.
• Each custom tool receives one plain-text input value and must return text or JSON.
• Select Test connection before saving. Ox uses a non-mutating HEAD probe, so testing never executes a configured POST action.
• A user can save up to four custom tools.
• An internet skill accepts a public Markdown/text URL, a GitHub repository URL, or a GitHub blob URL such as a checked-in SKILL.md file.
• Skill testing loads and validates the bounded content that Pi will receive.
• A user can save up to four internet skills, with one active for a turn.

Browser-configured MCP accepts up to three public HTTPS Streamable HTTP servers, up to eight tools from each server, and no more than sixteen remote tools in a turn. Context7 is included as a preset. Select Test to perform a real MCP initialize and tools/list exchange. Cross-origin redirects and private network targets are rejected.

• Auto activation connects for documentation and package prompts, or whenever the prompt mentions an enabled MCP server by name.
• Always connect opens every enabled remote MCP server on every tool-enabled turn.
• Remote MCP URLs must point to the single Streamable HTTP endpoint, commonly ending in /mcp.
• Browser-supplied secrets and credential-bearing URLs are rejected. Context7 can use the server-side CONTEXT7_API_KEY environment variable.

cp mcp.local.example.json mcp.local.json

OX_LOCAL_MCP_ENABLED=true
OX_LOCAL_MCP_CONFIG=/absolute/path/to/freeads-coder/mcp.local.json

[
  {
    "id": "mcp_local_project_docs",
    "name": "Project docs",
    "command": "node",
    "args": ["/absolute/path/to/server.js"],
    "cwd": "/absolute/path/to/project",
    "env": { "API_TOKEN": "${MY_MCP_API_TOKEN}" },
    "enabled": true
  }
]

Use OX_LOCAL_MCP_SERVERS_JSON instead of OX_LOCAL_MCP_CONFIG when inline configuration is preferable. Do not set both. Local definitions are never accepted from browser or CLI request bodies. They execute with the Ox service process permissions and must be operator-reviewed.

Pi does not include a host permission sandbox. Ox therefore never registers file or shell tools directly against the web server. When OpenShell is enabled, each user and workspace ID maps to a deterministic isolated sandbox whose working directory is /workspace.

• read returns bounded text or a supported image from the sandbox.
• write creates or completely replaces a text file and its missing parent folders.
• edit applies 1 to 20 exact, uniquely matching replacements and returns a unified diff.
• bash runs git, package managers, tests, builds, searches, and development commands inside the sandbox.

openshell status
openshell sandbox create --from base --name ox-smoke --detach
openshell sandbox exec --name ox-smoke --workdir /workspace --no-tty -- sh -lc 'pwd && git --version'
openshell sandbox delete ox-smoke

OX_OPENSHELL_ENABLED=true
OPENSHELL_GATEWAY=local
OX_OPENSHELL_SANDBOX_IMAGE=base
OX_OPENSHELL_SANDBOX_CPU=1
OX_OPENSHELL_SANDBOX_MEMORY=1Gi
OX_OPENSHELL_MAX_SANDBOXES=10
OX_OPENSHELL_MAX_EXEC_SECONDS=45
OX_MAX_AGENT_TURNS=8

openssl rand -hex 32

OX_CLI_API_TOKEN=replace-with-the-generated-token

export OX_CLI_API_TOKEN=replace-with-the-generated-token
npm run cli -- "Explain this TypeScript error"
npm run cli
npm link
ox-coder --help

OX_CODER_URL=https://ox.example.com ox-coder "Use the configured MCP tools"
git diff | ox-coder --skill review
ox-coder --workspace project-one --verbose "Run the tests and fix the failure"

Useful flags include --verbose for tool activity, --json for raw NDJSON, --workspace <id> for a persistent project, --no-workspace for advisory-only operation, and --no-tools to disable tools. Prefer the environment variable over --token because process arguments may be visible or retained in shell history.

Authorized JavaScript origin
https://oxcoder.tenstentgc.org

Authorized redirect URI
https://oxcoder.tenstentgc.org/api/auth/callback/google

NEXT_PUBLIC_APP_URL=https://oxcoder.tenstentgc.org
AUTH_URL=https://oxcoder.tenstentgc.org
NEXTAUTH_URL=https://oxcoder.tenstentgc.org
AUTH_TRUST_HOST=true
AUTH_SECRET=replace-with-a-long-random-value
AUTH_GOOGLE_ID=your-client-id
AUTH_GOOGLE_SECRET=your-client-secret
DATABASE_URL=postgresql://user:password@host:5432/database

The three public origin values must identify the same final HTTPS domain. Changing AUTH_SECRET invalidates existing sessions. On first database access, Ox creates the coder_chats table and an index by user key and update time. The application pool uses at most four PostgreSQL connections per process.

Public, content-led pages can render AdSense. This documentation page and the coding guides use the guides slot. The private chat does not render AdSense; it uses a separate direct sponsor interlude at the start of a generation.

NEXT_PUBLIC_ADSENSE_CLIENT_ID=ca-pub-0000000000000000
NEXT_PUBLIC_ADSENSE_LANDING_SLOT=0000000000
NEXT_PUBLIC_ADSENSE_GUIDES_SLOT=0000000000

NEXT_PUBLIC_SPONSOR_NAME=Partner name
NEXT_PUBLIC_SPONSOR_COPY=A concise product description.
NEXT_PUBLIC_SPONSOR_URL=https://partner.example/product

• The sponsor interlude remains visible for nine seconds and closes automatically.
• The sponsor link opens in a new tab without stopping generation.
• Rotating campaigns use NEXT_PUBLIC_SPONSOR_CAMPAIGNS_JSON with phone, foldable, or audio creative values.
• Until AdSense is configured and approved, public placements show a labeled mock technology campaign.
• The /ads.txt route publishes the configured AdSense seller record.

NEXT_PUBLIC_APP_URL=https://oxcoder.tenstentgc.org
AUTH_URL=https://oxcoder.tenstentgc.org
NEXTAUTH_URL=https://oxcoder.tenstentgc.org
AUTH_TRUST_HOST=true
NODE_OPTIONS=--max-old-space-size=384
MAX_ACTIVE_GENERATIONS=120
MAX_ACTIVE_GENERATION_UNITS=128

1. Create the service in the region nearest users and the database.
2. Add all required environment values as protected secrets where appropriate.
3. Add the custom domain, apply the displayed DNS record, and wait for TLS.
4. Verify /api/health, /api/auth/providers, Google sign-in, a text turn, an image turn, and cloud history in a private browser window.
5. Review production logs, memory, provider errors, and database connections before increasing capacity.

1. Auth.js validates a browser session, or the API validates a configured CLI bearer token.
2. The route applies per-user rate limits and weighted capacity admission before parsing the request.
3. Zod validates messages, model, attachments, tools, skills, MCP definitions, workspace selection, and response settings.
4. Ox infers the working method from the latest prompt and compacts older context when limits are reached.
5. Required MCP, internet skills, and OpenShell workspace tools are connected only when enabled and relevant.
6. Pi calls the selected OpenRouter model, validates tool calls, runs compatible tools, and continues for the configured number of turns.
7. Ox converts Pi events to newline-delimited JSON for activity, tool calls, reasoning, text, context, notices, usage, completion, and errors.
8. The browser renders events incrementally and persists the finished chat to PostgreSQL or browser storage.

The implementation aims for the practical Pi coding workflow: a model and tool loop, streaming, provider routing, MCP, and read, write, edit, and bash tools. Host execution is deliberately replaced by OpenShell isolation because a public web service needs a stronger permission boundary than a local terminal agent.

• Authentication protects the workspace and chat persistence routes.
• OpenRouter, database, Google, local MCP, and CLI secrets stay server-side and must never use a NEXT_PUBLIC_ prefix.
• Public URL tools resolve DNS and reject loopback, private, link-local, reserved, credential-bearing, and unsafe redirect targets.
• Readers enforce response-size limits, timeouts, content-type checks, and bounded redirects.
• Browser-defined tools and remote MCP require public HTTPS.
• Trusted local MCP definitions come only from server configuration and execute with the service account's OS permissions.
• File and shell operations run only through the separately managed OpenShell boundary.
• CLI tokens are compared using constant-time hashes and are never accepted in URLs.
• Request schemas cap conversation, attachment, tool, activity, reasoning, and stored output sizes.
• External webpages, skills, files, tool results, images, and videos are data, not trusted instructions.

{
  "model": "z-ai/glm-5.3-flash",
  "allowModelFallback": true,
  "messages": [
    { "role": "user", "content": "Review this API design" }
  ],
  "toolsEnabled": true,
  "enabledTools": ["calculate", "get_current_time", "search_web", "read_url"],
  "customTools": [],
  "internetSkill": null,
  "mcpServers": [],
  "mcpActivation": "auto",
  "workspace": { "id": "default", "enabled": false },
  "thinkingMode": true,
  "thinkingLevel": "medium",
  "contextCompaction": true,
  "providerRetries": 1,
  "maxAgentTurns": 8,
  "responseLanguage": "auto",
  "responseStyle": "balanced",
  "skill": "review",
  "customInstructions": "Prefer TypeScript and include verification steps."
}

The response Content-Type is application/x-ndjson with one JSON object per line. The route disables caching, aborts upstream work when the client disconnects, and allows at most 300 seconds for a multi-step turn.

When generation capacity is full, /api/chat returns HTTP 503 and Retry-After: 2. Rate limiting returns HTTP 429 with a calculated Retry-After value. Oversized chat requests return HTTP 413 before generation starts.

npm run typecheck
npm run lint
npm test
npm run build

• Verify Google login on the canonical domain.
• Verify cross-device chat history with PostgreSQL enabled.
• Run a text turn with every selectable model.
• Run image and video input with GLM 5.3 Flash, and image input with OpenRouter Free.
• Test one PDF, one remote attachment, every built-in tool, and the Context7 preset.
• When enabled, make a file change and run a command in an isolated workspace.
• Check sidebar, model menu, composer, settings, landing, journal, guides, docs, login, ads, and sponsor behavior on phone, tablet, and desktop widths.
• Inspect /api/health, deployment status, error logs, memory, provider errors, and database connections.