Get started

[ AxiomCore · Documentation ]

Run your first app

Clone the task app, run its Acore UI and API, and confirm that SQLite keeps your tasks.

Run a task list built with an Acore UI, an Acore backend and a real SQLite database, then confirm your tasks survive reloads and restarts. You need no Cloud account, extractor or database server.

The running task app listing two tasks stored in SQLite

The screenshot shows the app connected to its local API. The rows come from SQLite, not from mock responses.

The browser UI calls the local backend, which stores tasks in SQLite
The browser UI calls the local backend, which stores tasks in SQLite
Diagram source
flowchart LR
  A[Acore UI in the browser, port 5173] -->|request with API key| B[Acore backend, port 8080]
  B --> C[SQLite database file]

Prerequisites

  • Axiom CLI 0.149.1. This walkthrough is checked on macOS arm64.
  • git, a browser and two terminals. Ports 8080 and 5173 must be free.
  • The web UI host 0.6.12:
Terminal
axiom ui host install --target web --version 0.6.12 --non-interactive
Expected output
Verified and installed Axiom UI Host 0.6.12 (browser) for web.

1. Get the source

Terminal 1
git clone --depth 1 https://github.com/AxiomCore/AxiomCore.git
cd AxiomCore/examples/documentation/task-app

The shallow clone is about 6 MB. The example has three parts:

Project structure
task-app/
  backend/          # sqlite.acore, application.acore, Task.acore, AxiomDeps.toml
  database/sqlite/  # schema.acore, AxiomDeps.toml
  frontend/         # main.acore, AxiomDeps.toml

Each AxiomDeps.toml manifest belongs with its source. The frontend manifest points at the local backend contract and the API base URL http://127.0.0.1:8080.

2. Start the backend

From the task-app directory:

Terminal 1: task-app
unset DATABASE_URL
axiom check backend/sqlite.acore
axiom run backend/sqlite.acore --port 8080
Expected output
Valid backend contract: backend/sqlite.acore
Connected to <task-app>/database/sqlite/.axiom/database/data/database.sqlite · SQLite
Migration 1.0.0
  add Schemas.main
  add Tables.main.tasks
Validating migration internally…
Applied migration 1.0.0 · database verified
Development API key: <key>
Backend: http://127.0.0.1:8080

A JSON status line follows. The CLI created the SQLite database, applied schema version 1.0.0 and printed a development API key. Keep this process running and keep the key local. Unsetting DATABASE_URL stops the CLI from using an unrelated database from your shell.

3. Start the frontend

Open a second terminal in the same task-app directory:

Terminal 2: task-app
axiom run frontend/main.acore --target web --port 5173
Expected output
UI compiled (#1).
AUI059 development contract `tasks` uses an unsigned local artifact; a production release requires Axiom Cloud signing
Axiom UI is ready at http://127.0.0.1:5173/ (pass --launch to open a browser)

The AUI059 warning is expected: the local backend contract is unsigned.

Open http://127.0.0.1:5173. Paste the development key from Terminal 1 and select Connect. Add a task. After each change the list refreshes from the contract.

4. Verify persistence and errors

  1. Add two different tasks. Both appear in the list.

  2. Add a title that already exists. The app shows That task already exists; the API returned HTTP 409.

    The task app after submitting the existing title Write the release notes, with the message That task already exists shown beside and below the title field

  3. Reload the page and reconnect. Both tasks remain.

  4. Delete a task, reload and reconnect. The task stays deleted.

  5. Stop the backend with Ctrl-C, start it again with the same command, reconnect, and check that the remaining tasks are still there.

The backend also validates titles (1 to 120 characters) and supports renaming a task through the API. Task app shows the request shapes and the source behind each operation.

How the parts connect

  • frontend/AxiomDeps.toml binds the alias tasks to the backend contract at ../backend/.axiom/contracts/backend.axiom, with base URL http://127.0.0.1:8080, audience web and four operations.
  • backend/sqlite.acore maps the backend's tasks resource to the main.tasks table defined in database/sqlite/schema.acore. List responses return at most 100 tasks.
  • This is a local teaching app with one development identity and one tenant. It has no production login or deployment configuration.

Troubleshooting

SymptomFix
Web host missing or incompatibleInstall version 0.6.12 as shown; check it with axiom ui host status --target web.
UI cannot load tasksCheck that the backend is running, the key is pasted, and baseUrl in frontend/AxiomDeps.toml matches.
Port already in useChange the port in the command, the frontend manifest's baseUrl and the backend's cors origins in backend/application.acore together.
Wrong database selectedRun unset DATABASE_URL and restart the backend.
Edits to backend files have no effectStop both processes, run axiom build backend/sqlite.acore, then start both again.

To change the schema, change the database project version in database/sqlite/schema.acore before you apply it.

Cleanup

Stop both processes with Ctrl-C. The data stays in database/sqlite/.axiom/database/data/database.sqlite inside the clone. Keep the clone to continue, or delete the AxiomCore directory when you no longer need its data.

Next steps

Install the Axiom CLI

Install Axiom CLI 0.149.1, check your environment with axiom doctor and axiom onboard, and add the host, extractor or editor support your path needs.

Build your first API

Write a typed Acore endpoint, build its contract, run it locally and call it with curl.

On this page

Prerequisites1. Get the source2. Start the backend3. Start the frontend4. Verify persistence and errorsHow the parts connectTroubleshootingCleanupNext steps