Add an application
Tell Rehearsal where your application's source and container images are, pinned to exact versions, so a world can be built from it.
- Time
- 10 minutes
- Needs:
- a public git repository and published container images
An application is what a world is built from. Adding one costs nothing and starts nothing. The build is a separate step.
What your application must have
| Requirement | Why |
|---|---|
| A public git repository | The World Compiler reads the source to learn the services, the roles and the workflows. |
| Container images for every service | The application, its database, its worker and its cache each run from an image you list. |
| An HTTP API that staff use, REST or GraphQL | Agent tools are made from API operations. A published API description (OpenAPI, a GraphQL schema) helps a lot. |
| A database Rehearsal can read: PostgreSQL, MySQL, MariaDB or SQLite | Checks run there. |
| No need for outside services | A world has no internet access. Email, payments and webhooks are emulated or blocked. |
It also helps when the application has roles (administrator, agent, customer) and staff workflows where a mistake matters. Help desks, team chat, git hosting, content management, shops and CRM systems work well. Rehearsal is tested on Gitea, Chatwoot, Mattermost, WordPress and others.
One way to connect
Rehearsal connects to an application through its source and images. Other ways to connect, such as a running sandbox you already have, are not built.
Pin the source and the images
A world must be reproducible, so both the source and the images are pinned.
The commit is the full SHA, 40 characters. A branch or tag name is not accepted as a commit, because it can move. To get the SHA, check out the release you want and run:
git rev-parse HEADEach image is given with its digest: image:tag@sha256:.... A tag alone can be replaced by its publisher. To
get the digest of an image:
docker buildx imagetools inspect gitea/gitea:28.1.0Give each image a service name: gitea=..., postgres=.... List every service the application needs to start.
Write your policies
Policies are rules the agent must follow, in plain words. Write them as you would tell a new employee:
Never post a customer's account number in a public channel.
Only administrators create users.
Refunds over $200 need a manager's approval.Policies are optional. The build turns them into hard rules in the jobs: an agent that breaks one gets the outcome "rule violated".
Fictional data only
Do not put real customer data, real credentials or production addresses into an application or its policies. A world uses fictional data that Rehearsal creates.
Add it
- Open Applications and choose Add application.
- Enter a Name, the Git repository (https) and the Commit.
- Under Images, one per line, enter one
service=image@sha256:...on each line. - Under Rules agents must follow (optional), enter your policies.
- Choose Add application.
The values above are the real ones for Gitea from Rehearsal's catalog. You can use them to try a build.
The sample applications
Rehearsal ships a catalog of eight open-source applications, each pinned: Gitea, Chatwoot, Vikunja, WordPress, Mattermost, Odoo, Saleor and Easy!Appointments. To add them all, choose Load sample applications on the Applications page, or run:
rehearsal apps import-catalogThis adds eight applications at once, so the workspace's plan must keep eight or more. On a smaller plan, add one of them by hand with the values from this page.
Upload the source instead
When the server cannot fetch your repository, upload the source as an archive. Add the application without
--git, then upload a .tar.gz:
rehearsal apps add helpdesk --image app=acme/helpdesk:1.4@sha256:<digest>
rehearsal apps upload <app_id> helpdesk-source.tar.gzWhen it is refused
| Message | Cause | Fix |
|---|---|---|
commit must be a full lowercase hexadecimal object ID | The commit is a branch, a tag or a short SHA | Give the full 40-character SHA |
git source needs an HTTPS or git@host:path URL | The address has a user name, a password, a query or another scheme | Use the plain https:// address of the repository |
The Free plan keeps 1 application, and this workspace has 1 | The plan's count is used | Remove an application, or change plan |
application helpdesk exists | An application with this name is in the workspace | Choose another name |
Remove an application
In the console, open Applications and choose the bin icon beside the application. Over the API, removing needs
a key with "Full access": DELETE /v1/applications/<app_id>. Builds of it that are still
in progress stop. Finished runs stay in the history. The name becomes free again.
Next
Was this page helpful?