An extra is a machine of your own for containers the catalogue does not cover: a background remover, an OCR engine, a barcode reader. It is on your environment's private network, has its own disk, and runs your containers and nothing else.
Buying one
Buy an extra in the configurator with the environment, or add it later from the project's Resources tab. A shared plan has none.
Each environment has its own. Staging and development read the same
vallic.yaml, but production's extra is not theirs. Give staging one on the
Resources tab: a machine at full price, not a share of the machine staging
runs on.
When a deploy declares an extra the environment has no machine for:
| Environment | What happens |
|---|---|
| Staging, development | The extra is left out: the site deploys, the tool is not there, and no EXTRA_* variable names it |
| Production | The deploy is refused, because the site would call a tool that does not exist. Add the machine on the Resources tab and deploy again |
Two files
vallic.yaml says an extra exists and what your application may reach on it:
extra:
voyager:
expose:
rembg: 8001:8000
easyocr: 8002:8000
.vallic/extra/voyager.yml is an ordinary compose file, and says what runs:
services:
rembg:
image: ghcr.io/acme/rembg-api:1.4.0
environment:
U2NET_HOME: /cache/rembg
volumes:
- cache/models/rembg:/cache/rembg
healthcheck:
test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
easyocr:
image: ghcr.io/acme/easyocr-api:3.2.0
volumes:
- cache/models/easyocr:/cache/easyocr
Slots
Extras are called pioneer, voyager, galileo, magellan, cassini and
juno, allocated in that order. Buy two and you have pioneer and voyager.
The name is the machine, its hostname on the private network, the file it runs and the line on your invoice. You cannot choose it.
Ports
8001:8000 reads as compose's own port syntax. A single number means both.
In 8001:8000 |
What it is | Allowed |
|---|---|---|
| 8001 | The port the rest of your environment reaches | The reserved range, 8000 to 8008. No two services on one extra may use the same one |
| 8000 | The port your container listens on | Anything: 8000:80 is fine |
A service can answer on several:
expose:
api:
- 8003:8000
- 8004:9090
You do not write ports: in your compose file. The platform writes them,
bound to the private network.
Your data
A volume names a directory on the extra's own disk. Its first word says whether it is backed up:
volumes:
- keep/results:/var/results # backed up
- cache/models/rembg:/cache/rembg # not backed up
- keep/reference:/data/reference:ro # read-only, and backed up
| First word | For |
|---|---|
keep/ |
Anything you would be sorry to lose. It is included in your backups. To restore it, ask support and say which backup |
cache/ |
Anything the container can fetch or rebuild: model weights, scratch files, thumbnails. It is never backed up |
code/ |
Your own files, out of your repository: see Your own code on an extra |
- There is no default, and you have to pick one. A file that names neither is refused.
- Most model caches belong under
cache/: backing one up costs you storage and slows every backup. - The part after the first word is a name, not a path. The platform makes the directory and keeps it across deploys. You cannot name a path on the machine.
- A
keep/orcache/directory cannot be inside another one you mount:keep/dataandkeep/data/indextogether are refused. Mount the outer one and use the directory within it. Two services may mount the same directory. - These directories belong to the container's root user. An image built to
run as another user, such as
USER 10001, cannot write to them and fails at its first write. Give that serviceuser: "0": inside the container it is root, and on the machine it is still only your account. - An extra cannot see what your site has uploaded. A tool that needs your users' files, such as a thumbnailer, needs storage every machine can reach. That is a different purchase: ask support first.
Your own code on an extra
Put the files an image needs from you, such as an entrypoint, a config file or
a short script, in .vallic/extra/<slot>/ beside the compose file. Then mount
them:
.vallic/
extra/
voyager.yml # what runs
voyager/ # and the files it needs
rembg/
entrypoint.py
settings.toml
services:
rembg:
image: ghcr.io/acme/rembg-api:1.4.0
command: ["python", "/app/entrypoint.py"]
volumes:
- code/rembg:/app # .vallic/extra/voyager/rembg
code/rembgis always.vallic/extra/voyager/rembg. It cannot point anywhere else in your repository.- It comes from your release, not from your branch. An extra runs the code of whatever release your site is running. Deploy, and your extra picks up the new files and restarts.
- Deploy first. An extra that mounts code on an environment you have never deployed has nothing to run yet.
- It is read-only.
:rwon acode/mount is refused, because a deploy replaces the release whole. Put writable data underkeep/orcache/. - This is for scripts and configuration, not for an application.
Images, not builds
Name a published image and a version:
image: ghcr.io/acme/rembg-api:1.4.0 # good
image: ghcr.io/acme/rembg-api # refused — no version
image: ghcr.io/acme/rembg-api:latest # refused — moves under you
- A moving tag is replaced the next time the machine is reconciled, and nothing in your log explains why the behaviour changed.
- A digest pins hardest of all:
image: ghcr.io/acme/api@sha256:…. build:is not supported: extras run published images. Build your image in CI, push it to a registry, name the tag.
To change the version, commit the new tag and deploy. The extra follows your site's release: once the deploy is live, the extra's machine pulls the new image and replaces its container, usually within a minute. A rollback puts the previous tag back the same way.
Private registries
For a private registry, add a login on your project's Configuration
page, under Additional settings → Registry logins: the host as it appears
in the image (ghcr.io, registry.example.com:5000), a username, and a
password or token. A token that may pull is enough.
- The login belongs to the project, so every environment of it can pull the same image.
- Your machines use it only to fetch. It is never given to a container, never written into your compose file, and never shown back to you once saved.
- Replacing one means typing it again.
- Remove a login and it leaves your machines on their next reconcile.
Credentials
Do not put a credential in your compose file: every clone of your
repository would carry it. Name it in vallic.yaml instead, and set the
value in the console under Variables:
extra:
voyager:
expose:
rembg: 8001:8000
env:
required:
- REMBG_TOKEN
- S3_KEY
- Your containers get those variables and only those. An extra has no copy
of your site's
.env. - Asking for a name you have not set refuses the deploy, and the message says which one.
- Each slot gets its own. A name declared under
voyagerreaches the voyager machine and no other.
Logs
Whatever your containers print goes where the rest of your project's logs go. A destination of your own receives an extra's output too, stamped with the project and the environment. Every machine also keeps its own local copy.
There is no filter: a tool that prints a line per request sends a line per request. To store less, quieten the container.
What your compose file may say
A service may use these keys:
image, restart, environment, volumes, command, entrypoint,
healthcheck, depends_on, user, working_dir, stop_grace_period,
tmpfs, shm_size, ulimits, init, and your own x- keys.
Anything else is refused, and the message says why. The ones people reach for most:
| Key | Why not |
|---|---|
ports |
The platform binds these from your expose block, on the private network |
build |
Extras run published images: see Images, not builds |
networks, network_mode |
The platform draws the network your environment runs on |
env_file, secrets, configs |
These name files on the machine. Ask for variables by name under env.required instead |
privileged, cap_add |
Nothing on an extra runs privileged or reaches the machine |
devices |
Only to ask for the GPU an extra was bought with, by name: see A GPU. No path on the machine |
deploy |
The platform sets the limits: see What your containers may use. A GPU is asked for with devices |
container_name, labels |
The platform names and labels these |
- At the top level of the file, only
services,versionand your ownx-keys are allowed. Top-levelvolumes,secretsandconfigsare refused. - Volumes use the short form shown in Your data. The long form is refused.
- A file may declare up to 20 services and be up to 64 KB.
A GPU
An extra can be bought on a machine with a GPU: one NVIDIA card. Choose it in the configurator, on the extra's size, or add it to a running environment from the Resources tab. It is billed monthly like any machine.
| Card | Memory |
|---|---|
| L4 | 24 GB |
| L40S | 48 GB |
| RTX PRO 6000 | 96 GB |
The card's memory decides what fits, so choose by that. A GPU is for serving a model to your site over the private network: embeddings for search, a chat or summarising model, speech to text, OCR.
Where it is built
- GPUs are in one datacentre. The machine is built there and joined to your environment's private network, wherever in the same part of the world your environment is.
- The size list says where each one is built.
- Your application reaches it as it reaches any extra, through the
EXTRA_*variables. - From another datacentre a request takes a few tens of milliseconds more.
- GPU machines are offered only where your environment can be joined to that datacentre, and only for an extra: never as the machine your site runs on.
The disk
A GPU machine is bought with a disk: 100 GB to start, enough for a serving image and a model of a few tens of gigabytes. Make it larger in the configurator, or later from the machine's resize dialog. Its price is a line of its own.
Asking for the card
Ask for the card in the service that uses it:
services:
llm:
image: docker.io/vllm/vllm-openai:v0.33.0
command: ["--model", "Qwen/Qwen2.5-1.5B-Instruct", "--max-model-len", "4096"]
shm_size: 8g
devices:
- nvidia.com/gpu=all
volumes:
- cache/huggingface:/root/.cache/huggingface
devicesnames the card, and nothing else. Writenvidia.com/gpu=all, ornvidia.com/gpu=0for the first card. A path on the machine is refused, and so is compose'sdeployway of asking.- A service without the line does not get the card. A web front or a queue beside your model server shares the machine without it.
- On a machine without a GPU, a deploy that asks for one is refused, with a message saying so.
- The driver is on the machine; CUDA is in your image. The machine runs NVIDIA's driver with support for CUDA 13 and the toolkit that hands the card to a container. Use an image built for CUDA 13 or earlier, as the model servers' published images are.
- Model servers want shared memory.
shm_sizegives it;ipc: hostis refused. - Most model servers download their model on first run. That needs
egress: internetinvallic.yaml. Put the weights undercache/, which is kept across restarts and deploys and never backed up. Or put the model in your image and need no internet at all. - Memory and CPU are shared between your services as on any extra. The card's memory is the model's: only the services that ask for the card use it.
If the card stops being usable, we are told and put it right. A deploy meanwhile says so rather than starting a container that would fail.
What it can reach
Your application calls an extra over the private network. That direction always works.
Outward, it is closed by default. Its containers may reach the machines running your application and nothing else: not your database, not your cache or session store, not the internet.
Calling your application back
Every service on an extra is given your application's private address:
VALLIC_APP_URL=http://10.16.0.2:8082
VALLIC_APP_HOSTNAME=example.com
Call $VALLIC_APP_URL with the Host header set to $VALLIC_APP_HOSTNAME:
curl -H "Host: $VALLIC_APP_HOSTNAME" "$VALLIC_APP_URL/api/callback"
A call without that header is not your site. Any of your site's own names works.
- Private all the way. The call never leaves your environment's private network, so it goes past the CDN and your site's visitor protections: allow and deny lists, password, rate limit.
- Treated as HTTPS. Your application is told the request is secure, so it
builds
https://links and does not redirect it. - The extra's own address. Your application sees the extra's address as
the caller's, whatever the extra sends in
X-Forwarded-For. - One machine. Where your application runs on several, the URL names the first. A call made while that machine is being replaced fails, so retry it.
Reaching the internet
If a tool needs the internet, say so in vallic.yaml:
extra:
voyager:
expose:
rembg: 8001:8000
# rembg fetches its model on first use
egress: internet
internetis the only thingegressmay say. A list of hostnames is not offered.- Without it, a container that needs the internet starts and then hangs on its first request out. That reads like a broken image.
- The internet is reached through a proxy. Your containers are given
HTTPS_PROXYandHTTP_PROXY, and web requests (HTTP and HTTPS, ports 80 and 443) go out through them. Set them in your compose file and they are replaced. - Most tools and libraries honour those variables without being asked. One that does not, or that needs another port, cannot reach the internet from an extra.
- Images are pulled through your environment's front machine when the extra may not reach the internet. The front fetches only from the registries your images name and the registries you have logged in to.
Reaching it from your application
Your application is given the extra's address in its environment. It is assigned when the machine is built, so you cannot write it down yourself.
For the example in Two files:
EXTRA_VOYAGER_HOST=10.16.0.7
EXTRA_VOYAGER_REMBG_PORT=8001
EXTRA_VOYAGER_EASYOCR_PORT=8002
So http://$EXTRA_VOYAGER_HOST:$EXTRA_VOYAGER_REMBG_PORT reaches rembg. A
service that declares several ports gets the first, and your manifest names
the rest.
Nothing else reaches an extra: not the internet, and not your site's domain, unless you publish a path.
Publishing a path of your site
An API your extra answers can be served under a path of your site's own
domain. Here https://example.com/api/ reaches the extra and every other
path is your site:
extra:
pioneer:
expose:
engine: 8001:8080
public: /api/
The engine listens on 8080 inside its container and is reached on 8001, from the same band as any port of an extra. Where the extra exposes several ports, name the one, by that outside port:
public:
path: /api/
port: 8001
- One path per extra, beginning and ending with a slash. No two extras may be on paths where one contains the other.
- The path is passed on as it is.
/api/v1/jobsarrives at the extra as/api/v1/jobs. - Not a path your site or the platform needs.
/admin/,/batch/,/core/,/libraries/,/modules/,/profiles/,/sites/,/system/,/themes/,/update.php/,/user/,/vallic/,/vendor/and/.well-known/are refused. - The same protections as your site. Your allow and deny lists, password, rate limit and the platform's request checks apply to these requests as they do to your pages. A rate limit set for your pages limits your API too.
- Never cached. Answers carry
Cache-Control: no-store, whatever your service sends, so neither the CDN nor a Varnish tier keeps one. - Your service's errors are its own. A failing extra answers with its own
status, or
502where it is not answering at all. Your site's error and maintenance pages are not shown in their place, except that an environment in maintenance is in maintenance on this path too. - Requests are read within 60 seconds. A large upload over a slow line has to arrive in that time. Work that takes longer belongs in a job your API starts and answers about later.
- Call your primary domain. Your site's own names carry the path, and a name that redirects to your primary domain redirects for this path too.
What your containers may use
The platform sets these limits on your containers. You do not write them and cannot raise them from the file.
| Resource | Limit |
|---|---|
| Memory | Divided between the services in your file: one service has the machine's memory, two have half each. A container that runs out of memory is killed |
| CPU | Not divided. Every container may use the whole machine, and they share it when more than one is busy |
| Processes | 512 for each container |
If you run several services, size the machine for their total rather than for the largest. One that wants a lot on its own is usually better on an extra of its own.
If your machine is the wrong size for what you are running, resize it, add another extra on the Resources tab, or ask support.
Knowing it is unwell
The console shows what each of your containers is doing: whether it is running
and, if your image declares a healthcheck, whether that check is passing.
- A container that is running and well is not listed. One that has stopped or is failing its check is.
- An image that declares no healthcheck is never reported as healthy.
- A container being unwell is not by itself an outage. Your extra's containers do not fail your deploys.
Design for the tool being unavailable. What counts as downtime is under Uptime and support.
Uptime and support
Your uptime SLA does not cover an extra. An extra's downtime is not counted against the promise, and you are not charged for the SLA on it. The uptime price is calculated from your other machines.
Uptime is measured against your site's hostnames. If your site returns errors because an extra is down, your site is down, and that does count.
Support does cover it, and the support price includes it.
What it does not have
No release of your code, no .env, no cron, and no shell. Secrets your
containers need are yours to put in their environment, or to ask support
about; the environment's own variables are not handed to them.
Thank you. Good to know it helped.
Thanks — tell us what was missing. Open a ticket from Support in the console, and we answer on the ticket. Open the console