On this page

Deploy Links

A link to https://app.guaracloud.com/services/new can carry query parameters that pre-fill the new service wizard. Use these links for Deploy on Guara Cloud buttons in READMEs, templates and docs, or have the CLI, MCP or an agent build one for you.

Examples

A service built from a Dockerfile in a GitHub repository:

https://app.guaracloud.com/services/new?name=My%20API&source=dockerfile&repo=https://github.com/org/app&branch=main&dockerfile=Dockerfile&port=3000&service_type=web&env.LOG_LEVEL=info

A service deployed from a public image:

https://app.guaracloud.com/services/new?name=My%20API&source=image&image=ghcr.io/org/app:latest&port=8080&is_public=true

A button in a README:

[Deploy on Guara Cloud](https://app.guaracloud.com/services/new?name=My%20API&source=buildpack&repo=org/app)

URL-encode the values: a space becomes %20, and a & or # inside a value must be encoded (%26, %23).

Parameters

Each parameter has a full name matching the wizard field, and some have a shorter alias. Both work.

ParameterAliasStepValue
projectTopProject ID. Falls back to the default project if the visitor can’t create services in it.
nameSourceService name, 3 to 40 characters. The slug is generated from it.
sourcebuild_methodBuilddockerfile, buildpack (default) or image.
service_typeBuildweb (default) or worker.
github_repo_urlrepoBuildhttps://github.com/owner/repo or owner/repo. Dockerfile and Buildpack only.
github_branchbranchBuildBranch to deploy. Needs repo.
github_root_directoryrootBuildDirectory the build runs in, such as /apps/api. Needs repo.
dockerfile_pathdockerfileBuildPath relative to the root directory, without ... source=dockerfile only.
build_commandBuildsource=buildpack only. No ; & $ \ ( ) { } < >, pipes or backticks.
start_commandBuildsource=buildpack only. Same rules as build_command.
image_referenceimageBuildImage reference, such as ghcr.io/org/app:1.2. source=image only.
env.<KEY>EnvironmentOne environment variable per parameter, such as env.LOG_LEVEL=info.
portResources1 to 65535 (default 3000). Web services only.
is_publicResourcestrue or false (1 or 0). Web services only.
storage_enabledResourcestrue or false. Adds a persistent volume.
storage_size_miResourcesSize in MiB, at least 128. Needs storage_enabled=true. Plan limits are checked on create.
volume_mount_pathResourcesAbsolute path, such as /data (default). Needs storage_enabled=true.

Parameters only apply where the wizard shows that field. For example, image is ignored unless source=image, and port is ignored for a worker. When source is missing, the wizard opens on Buildpack.

Leave project out of public buttons: project IDs belong to one account. It’s for links built for a specific person, such as by the CLI or an agent.

The GitHub repository

The wizard selects the repository only when the visitor’s GitHub App installation can see it. If it can’t, the wizard says so and the visitor can grant the app access to that repository or pick another one. The branch is selected only if it exists; otherwise the repository’s default branch stays selected.

For a public template, the visitor deploys their own copy: link to the template and ask them to fork it, or point repo at a repository they already have.

Environment variables

Add one env.<KEY>=<value> parameter per variable. Keys follow the same rules as the wizard: letters, digits and underscores, starting with a letter or underscore. Reserved names such as PORT, NODE_ENV, PATH or anything starting with GUARA_ are ignored. An empty value is allowed (env.FEATURE_FLAG=).

Security restrictions

Links travel through browsers, chat and logs, so they never carry secrets:

  • Registry credentials (registry_url, registry_username, registry_password) are never applied. Add them in the wizard’s private registry section.
  • Environment variables whose name looks like a secret are dropped: names containing SECRET, TOKEN, PASSWORD, PASS, PWD, PRIVATE_KEY, CREDENTIALS, API_KEY or ACCESS_KEY.
  • Environment variables whose value looks like a credential are dropped, whatever their name: URLs with an embedded password (postgres://user:password@host), private keys, and GitHub, Stripe, Slack, AWS or JWT tokens.

Add those values yourself in the Environment step, or after the service is created.

Anything the wizard doesn’t apply (unknown, invalid, repeated, secret, or not applicable to the chosen options) is listed by name in the notice at the top of the wizard, never with its value. Everything else stays filled in. When a parameter appears twice, the first value wins.

Visitors who aren’t signed in

A visitor without a session goes to the sign-in page first, then lands back on the wizard with the same parameters. This also works for new accounts. Keep links under 2,000 characters so they survive sign-in by email link.