Cloud mocks

A Cloud mock lets frontend developers and tests call your API before the real backend exists. There are two connected but separate steps:

1. Save the project's mock configuration to Axiom Cloud with axiom deploy mock-server.
2. Run it, either locally with axiom mock --cloud or in the managed sandbox that Cloud starts from a verified release.

Saving the configuration does not by itself prove that a managed sandbox is ready.

Diagram source

sequenceDiagram
  participant Dev as Developer
  participant CLI as Axiom CLI
  participant Cloud as Axiom Cloud
  participant SB as Managed sandbox
  Dev->>CLI: axiom deploy mock-server
  CLI->>CLI: Evaluate axiom.acore and render JSON
  CLI->>Cloud: Save mock configuration
  Cloud-->>SB: New revision, if a sandbox is live
  Dev->>CLI: axiom mock --cloud
  CLI->>Cloud: Fetch configuration with its ETag
  Cloud-->>CLI: Configuration, or not modified
  CLI-->>Dev: Contract mock on localhost

Save mock configuration

From a directory linked to your project (see Workspaces and projects):

axiom deploy mock-server axiom.acore

The file argument is optional and defaults to axiom.acore. The command checks the directory link, evaluates the local Acore module, renders the result to JSON and uploads it to the linked project. Maintainers and owners can save configuration. You can also edit it under Mock configuration on the project's Sandbox page.

Each project keeps one saved configuration. A new save replaces it, and Cloud does not check it against your contract. If a sandbox is live, saving queues a new revision of that sandbox.

The command evaluates the file with the local project evaluator. Treat imported or amended code with the same care as any code you run; see How extraction works.

Run a mock locally

axiom mock --cloud fetches the saved configuration and runs it as a local contract mock:

axiom mock --cloud --port 8080

It needs a linked directory and a Cloud session. It keeps a cached copy and its ETag, so an unchanged configuration is not downloaded again. It runs only the contract profile and rejects a local input file, --variant, --plan, --deployment, --bindings, --delivery, --fixtures, --identities and --watch.

Local mocks never fall back to Cloud. To simulate a local contract offline, pass the file:

axiom mock axiom.acore --profile contract --port 8080

axiom serve starts your real local API. It never downloads a saved Cloud mock. See Mocks for local mock profiles and fixtures.

Serve it from the managed sandbox

After a release is verified, open the project's Sandbox page and choose Launch from active release. Provisioning runs in the background. Wait for the sandbox to report ready before you give its endpoint to a consumer or queue a sandbox-backed test. See Releases and environments for the sandbox lifecycle and key.

An empty mock document is valid, but it does not invent successful behavior. A contract route with no declared behavior returns an explicit 501 response with mock_behavior_not_declared.

Security checklist

• Use synthetic data only.
• Never put provider, database or production user credentials in the mock.
• Require the sandbox key for routes, health controls, reset and API docs.
• Redact the key from screenshots, shell history, logs and test artifacts.
• Check that reset restores the declared initial state.
• Confirm that expiry or deletion removed the sandbox before you treat it as gone.

Next steps

• Follow a release into the managed sandbox
• Write contract tests that run against the sandbox
• Choose a local mock profile