Run APEXREST in Codex Cloud

Run APEXREST's bundled CLI inside the Cloud container, using ORDS over HTTPS for database access. The example below adapts a project-specific Cloud bootstrap into reusable scripts. It does not register the plugin or expose its MCP tools and skills to the Cloud agent. Those integrations require their own host verification; see host integration.

1. Prepare your application repository

Copy the files in the Cloud example directory into scripts/codex-cloud/ in the application repository connected to Codex Cloud. Keep all files together. From your application repository, with a local APEXREST checkout available:

mkdir -p scripts/codex-cloud
cp /path/to/apexrest/docs/examples/codex-cloud/* scripts/codex-cloud/

Add these entries to the application's .gitignore before running setup:

.codex/cloud/
.apexrest/

Commit the example scripts and ignore rules to the repository's default branch used for Cloud cache preparation, and ensure they are also present on the task branch. Cloud checks out the task branch when resuming the cache; see container caching. Generated tools, credentials, logs, plans and backups must remain private. The scripts are documentation examples, not files automatically installed by the plugin or its npm package.

The version file pins a reviewed immutable checkout with manifest version 2.0.0. Setup verifies the commit and version, then uses plugins/apexrest-apex/runtime/apexrest.mjs; it needs neither an npm release nor a TypeScript build. Review and change both pins together when adopting another build. The bootstrap and connected workflow require verification in the actual Cloud environment.

2. Configure the Cloud environment

Select your application repository in Codex Cloud environment settings. Select Node.js 24 and Java 21 under package versions. Java must be a JDK with jdk.compiler, not just a JRE. Git and Bash must also be available.

Set the following environment variables. Replace every target placeholder with values supplied for your development/test environment:

Add APEXREST_ORDS_PASSWORD as a Secret, not a normal environment variable or repository file. The account must already have authorized access to REST-Enabled SQL on that ORDS schema. Use the schema URL, not an APEX application URL or the /_/sql endpoint; see ORDS configuration.

Cloud secrets are available during setup, then removed from the agent environment. This example deliberately retains a credential file for later CLI commands. Cloud container caching can retain that file, and Business/Enterprise caches can be shared by environment users. Use an environment whose users are authorized for that database account. See OpenAI's Cloud environment documentation.

With APEXREST_PERSIST_CREDENTIALS=1, setup passes the secret through a temporary owner-only file to connection add --password-file, removes the temporary file, and keeps the APEXREST credential under .codex/cloud/tools/credentials/ with POSIX mode 0600. This is not an encrypted vault: the agent and processes running as the same user can read it. If this retention is unsuitable, do not enable the flag or use this connected example. Never print the secret, enable shell tracing, or include .codex/cloud/ in commits or shared artifacts.

3. Set setup and maintenance commands

Setup script:

bash scripts/codex-cloud/setup.sh

Maintenance script:

bash scripts/codex-cloud/setup.sh --maintenance

Setup checks the pinned checkout, previews and installs managed dependencies, prepares a private JDK, selects sqlcl configure --mode cli --database-transport ords, saves the connection and runs doctor plus a read-only database identity check. It creates no application or business data and grants no deployment permission.

Maintenance reuses the installed build and credentials, refreshes Java proxy/CA settings and repeats the connection check. It does not reinstall dependencies. For a missing build, changed pin or missing credential, rerun setup with the secret available. For credential rotation, update the Secret and rerun setup; retaining an old local credential is not rotation.

The launcher restores APEXREST_HOME, APEXREST_JAVA_HOME and the selected Node executable on every invocation. A setup-only export would not persist into the agent phase. Cloud may resume a cached container and run maintenance; after incompatible setup changes, use Reset cache. See environment lifecycle.

4. Configure network access

Enable agent internet access for the exact ORDS hostname and allow POST, which REST-Enabled SQL needs even for read-only queries. Setup download access and agent-phase access are separate settings. See OpenAI's agent internet access documentation.

The example uses HTTPS because a Cloud HTTP proxy does not establish reachability to the Oracle listener on port 1521; plain http: ORDS URLs are accepted only for loopback. It makes no listener-connectivity assumption. Setup also needs access to the canonical GitHub repository and the dependency download hosts shown by the installer preview.

The network helper enables NODE_USE_ENV_PROXY=1. Vendor downloads then honor HTTPS_PROXY and NO_PROXY; if a proxy is configured but the running Node cannot apply it, setup stops with PROXY_UNSUPPORTED rather than bypassing the proxy. The Java helper copies the environment JDK into .codex/cloud/java, writes proxy settings to its private conf/net.properties and imports the environment CA bundle from NODE_EXTRA_CA_CERTS into its private lib/security/jssecacerts. It preserves the default trust roots and leaves the host JDK unchanged. APEXREST strips Java option environment variables for Oracle subprocesses, so JAVA_TOOL_OPTIONS alone is insufficient here.

The helper accepts an HTTP proxy without URL credentials, reading https_proxy, HTTPS_PROXY, http_proxy, then HTTP_PROXY. Host/domain entries in NO_PROXY are mapped to Java; CIDR entries remain proxied. Unsupported proxy settings fail explicitly. Keep TLS certificate verification enabled; refresh the private truststore when the environment CA changes.

5. Verify from a Cloud task

Start a task after successful setup and run these commands from the application repository. Replace cloud-dev if you chose another reference:

bash scripts/codex-cloud/apexrest doctor --json
bash scripts/codex-cloud/apexrest sqlcl status --json
bash scripts/codex-cloud/apexrest connection list --json
bash scripts/codex-cloud/apexrest connection test --name cloud-dev --json
bash scripts/codex-cloud/apexrest --help

Check the actual JSON and exit codes: the selected mode must be cli, network transport ords, and the connection identity must match your intended database/schema. A successful doctor command is insufficient: it reports probes separately and does not test the database. Its nativeHost: requires-host-verification and database: not-configured fields do not override a separately successful connection test. A missing local Codex executable also does not by itself prevent direct CLI/ORDS operations.

The connection reference belongs to APEXREST, not SQLcl's saved connection store; do not replace the command with sql -name cloud-dev or connection test --saved. Save only sanitized evidence; identity output can contain private target names.

6. Give the agent project instructions

Add a short Cloud-specific section to the application repository's AGENTS.md:

## APEXREST in Codex Cloud

- Run APEXREST commands with `bash scripts/codex-cloud/apexrest`.
- Check doctor, SQLcl configuration and the configured connection identity first.
- Use SQLcl CLI with ORDS; this bootstrap does not register native plugin tools.
- Keep `.codex/cloud/` and `.apexrest/` private. Never print credentials.
- Do not run setup, native plugin registration or dependency downloads in every task.
- Use the configured project/environment and existing deployment safeguards.
- Report compiler checks, database checks and browser observations separately.

Before application work, configure the target in apexrest.json, including workspace, schema, application ID, database identity and the correct read/deploy references. Follow the safety rules and retain validation, backup, exact-plan authorization, drift and unknown-outcome protections from configuration and deployment safety. Installation and a successful connection test do not authorize an import.

The example keeps local deployment history under APEXREST_HOME. Cloud caches are not durable backup storage or cross-container coordination: preserve private backups/history outside an expiring container and serialize runners before authorizing deployments. Do not reset away an unresolved operation's records or silently start fresh history against the same schema.

Browser dependencies are skipped. Browser checks require separately configured tools, authentication and actual observations. The CLI bootstrap does not establish that $apexrest-work or automatic skill/MCP discovery work in Cloud; the CLI equivalents of the work cycle are apexrest apex validate, apexrest ship --mode plan|apply --user-request TEXT and apexrest job status. Use the launcher for the documented flow and report unavailable checks explicitly.

Troubleshooting

Verification scope

Local script syntax and package checks do not establish an actual Cloud setup/resume, connected Oracle operation, native plugin discovery or browser session. Complete the checks above on the intended environment and record the resulting scope; see implementation status and next actions.

View this page source