Apps

An app is one deployable unit: a repository, an uploaded archive, a Docker image or a compose stack. Its settings have their own page, App settings; shipping it is on Deployments.

ReadingCopy Anchor Link

appsCopy Anchor Link

Any signed-in principal. Returns [App!].

All apps in the active team, newest first.

query {
  apps(q: "shop") {
    id
    slug
    name
    status
    latestDeployment { status createdAt }
  }
}

appCopy Anchor Link

Any signed-in principal. Returns App.

One app by its team-scoped slug, or null.

query {
  app(slug: "shop") {
    id
    name
    status
    productionUrl
    framework
    deployments { id status createdAt }
  }
}

searchCopy Anchor Link

Any signed-in principal. Returns SearchResults.

Find anything by name, slug or id across EVERY team the caller can reach - the one read in Deplo that is not scoped to the active team. Each hit says which team it is in. Separators and case are ignored, so "better auth" finds better-auth-docs. Hits from the active team come first, then the closest match. Teams the caller cannot enter right now (an unmet two-factor policy, a narrowed token) contribute nothing rather than failing the search.

query {
  search(q: "shop", kinds: [app, database]) {
    apps { id slug name team { slug } }
    databases { id name team { slug } }
  }
}

appRuntimeCopy Anchor Link

Any signed-in principal. Returns AppRuntime.

Live container state for an app, straight from the owning agent - the truth behind the stored status. Polled by the app's status badge.

query {
  appRuntime(appId: "prj_9f1c2ab7d3e4f5a6") {
    running
    total
    unhealthy
    unreachable
  }
}

overviewAppStatesCopy Anchor Link

Any signed-in principal. Returns [OverviewAppState!]!.

Batch runtime state for the visible Overview apps. Unknown or inaccessible IDs are omitted.

query {
  overviewAppStates(appIds: [["prj_9f1c2ab7d3e4f5a6"]]) {
    status
    appId
    neverDeployed
  }
}

appTransferInfoCopy Anchor Link

Needs move_apps. Returns AppTransferInfo.

What transferring this app to another team would change, and which of the viewer's other teams could take it.

query {
  appTransferInfo(appId: "prj_9f1c2ab7d3e4f5a6") {
    appName
    targets {
      id
      name
      serverAvailable
    }
  }
}

CreatingCopy Anchor Link

createApp takes the whole first configuration in one input. The new-app wizard runs detectRepoFramework while you pick a repository and composeNameClashes before it submits a stack.

createAppCopy Anchor Link

Needs create_apps. Returns App.

Create an app from a repository, an uploaded archive, a Docker image or a compose stack, with its first build settings, variables, domains and mounts. Deploys immediately unless the source needs an upload first.

mutation {
  createApp(
    input: {
      name: "shop"
      source: GITHUB
      repo: { provider: "github", repo: "acme/shop", branch: "main", url: "https://github.com/acme/shop", installationId: "ghi_9f1c2ab7d3e4f5a6" }
      build: { buildMethod: "nixpacks", port: 3000 }
      env: [{ key: "NODE_ENV", value: "production" }]
      autoDeploy: true
    }
  ) {
    id
    slug
    name
    status
    productionUrl
  }
}

createAppFromTemplateCopy Anchor Link

Needs create_apps. Returns App.

Create an app from the public template catalog. deploy: true builds it right away.

mutation {
  createAppFromTemplate(
    input: { templateSlug: "umami", name: "analytics", deploy: true }
  ) {
    id
    slug
    name
    status
    productionUrl
  }
}

templateVariantsCopy Anchor Link

Any signed-in principal. Returns [TemplateVariantSummary!].

List the compact deployable variants in the public template catalog.

query {
  templateVariants(q: "analytics") {
    templateSlug
    variantSlug
    name
    category
  }
}

refreshTemplatesCopy Anchor Link

Any signed-in principal. Returns Boolean.

Drop the cached template catalog so the next read hits the catalog service.

mutation {
  refreshTemplates
}

composeNameClashesCopy Anchor Link

Needs create_apps. Returns [ComposeNameClash!].

The service names a stack would share with something already on the network it lands on - what createApp refuses it over, asked before creating so the caller can pass renameClashes instead. Empty when nothing clashes.

query {
  composeNameClashes(
    input: { compose: "services:\n  web:\n    image: nginx\n", serverId: "srv_9f1c2ab7d3e4f5a6" }
  ) {
    name
    owner
    renamedTo
  }
}

detectRepoFrameworkCopy Anchor Link

Needs create_apps. Returns RecognizedFramework.

Read a GitHub repository before an app exists for it - the framework and the build command the new-app wizard prefills while you pick a repo. Null when there is nothing to read at all: a build method other than Nixpacks / Railpack (the only ones this applies to), a repository Deplo can't read, or one with neither a framework nor a script. Reads only; the app's first deploy re-derives and stores the framework.

query {
  detectRepoFramework(repo: "acme/shop", buildMethod: "nixpacks", installationId: "ghi_9f1c2ab7d3e4f5a6") {
    id
    name
    buildCommand
    startCommand
    defaultPort
  }
}

Running and stoppingCopy Anchor Link

startAppCopy Anchor Link

Needs control_apps. Returns App.

Start a stopped app from its last deployment.

mutation {
  startApp(id: "prj_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    status
    productionUrl
  }
}

stopAppCopy Anchor Link

Needs control_apps. Returns App.

Stop the app's containers without deleting anything.

mutation {
  stopApp(id: "prj_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    status
    productionUrl
  }
}

reloadAppCopy Anchor Link

Needs control_apps. Returns String.

Re-apply the app's routing (domains + basic auth) to the running stack without a rebuild. Returns 'rerouted', 'unchanged', or 'deferred'.

mutation {
  reloadApp(id: "prj_9f1c2ab7d3e4f5a6")
}

rebuildAppCopy Anchor Link

Needs deploy_apps. Returns App.

Rebuild the image from the current source and REPLACE the running container, even if nothing about the stack changed. Volumes, domains and data are untouched.

mutation {
  rebuildApp(id: "prj_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    status
    productionUrl
  }
}

bulkAppActionCopy Anchor Link

Needs control_apps. Returns BulkAppActionResult.

Start, stop or restart EVERY app in one folder (its whole subtree) or one project (every environment). Gated again per app, so it only touches the ones the caller may control; one failure never stops the rest. Give exactly one of folderId / projectId.

mutation {
  bulkAppAction(action: restart, folderId: "fld_9f1c2ab7d3e4f5a6") {
    ok
    failed
  }
}

bulkRedeployAppsCopy Anchor Link

Needs deploy_apps. Returns BulkAppActionResult.

Redeploy EVERY app in one folder (its whole subtree) or one project (every environment): the bulk twin of redeploy. Give exactly one of folderId / projectId.

mutation {
  bulkRedeployApps(projectId: "prc_9f1c2ab7d3e4f5a6") {
    ok
    failed
  }
}

Renaming, moving and deletingCopy Anchor Link

renameAppCopy Anchor Link

Needs configure_apps. Returns App.

Rename an app. The slug, and with it the auto domain, stays as it is.

mutation {
  renameApp(id: "prj_9f1c2ab7d3e4f5a6", name: "shop") {
    id
    slug
    name
    status
    productionUrl
  }
}

reorderAppsCopy Anchor Link

Needs manage_team, or instance admin. Returns Boolean.

Set the team-wide display order of apps in Overview.

mutation {
  reorderApps(appIds: [["prj_9f1c2ab7d3e4f5a6"]])
}

transferAppToTeamCopy Anchor Link

Needs move_apps. Returns Boolean.

Hand this app over to another team the viewer belongs to. A live app restarts briefly on that team's network (nothing is rebuilt); it leaves its folder/project, loses its shared-variable links, backup schedules and cron jobs, and keeps its GitHub connection only if the destination team has its own installation on that account. Returns true.

mutation {
  transferAppToTeam(
    appId: "prj_9f1c2ab7d3e4f5a6"
    teamId: "team_9f1c2ab7d3e4f5a6"
  )
}

deleteAppCopy Anchor Link

Needs delete_apps. Returns Boolean.

Delete the app. Returns as soon as the deletion is RECORDED - from that moment the app is refused by every gate and gone from the product, and the stack teardown finishes on the host behind the response. Its stored backups are deleted first; if one cannot be, nothing is deleted.

mutation {
  deleteApp(id: "prj_9f1c2ab7d3e4f5a6")
}

deleteAppsCopy Anchor Link

Needs delete_apps. Returns Int.

Bulk-delete several apps. Returns how many were recorded as deleted; the bounded-concurrency teardown runs behind the response.

mutation {
  deleteApps(ids: ["ids"])
}

Logo and frameworkCopy Anchor Link

updateAppLogoCopy Anchor Link

Needs configure_apps. Returns App.

Set the app's logo (an image data-URI), or clear it with null.

mutation {
  updateAppLogo(id: "prj_9f1c2ab7d3e4f5a6", logo: "data:image/png;base64,…") {
    id
    logo
  }
}

detectAppLogoCopy Anchor Link

Needs configure_apps. Returns App.

Auto-detect a favicon from the app's own files - its GitHub repo, its uploaded archive, or (for a compose stack) its files dir on its server, and set it as the logo. Errors if none is found.

mutation {
  detectAppLogo(id: "prj_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    status
    productionUrl
  }
}

setAppFrameworkCopy Anchor Link

Needs configure_apps. Returns App.

Correct the framework Deplo recognised in this app's source (a catalog id such as "vite"), or pass null to go back to trusting detection. The correction survives every later deploy's re-detection.

mutation {
  setAppFramework(id: "prj_9f1c2ab7d3e4f5a6", framework: "vite") {
    id
    framework
  }
}

SubscriptionCopy Anchor Link

appStatusCopy Anchor Link

Any signed-in principal. Returns App.

Emits the app whenever its status (power / deployment) changes. Fires once immediately with the current snapshot, then on every change.

subscription {
  appStatus(slug: "shop") {
    id
    status
    latestDeployment { id status }
  }
}

See alsoCopy Anchor Link