Key Concepts

Devpilot organizes your infrastructure around a small set of core concepts that work together in a clear hierarchy. Understanding these concepts and their relationships helps you use the platform effectively from day one.

Platform hierarchy

Devpilot's model follows two hierarchies inside a workspace that meet at the deployment:

Workspace
├── Projects
│   └── Apps
│       └── Deployments (with a pipeline of Hooks)
├── Servers (provisioned or connected)
├── Integrations (source control and cloud providers)
└── Members (Owner, Admin, Member)

An App lives inside a Project and points at a Server. A Deployment is the act of pulling code from a Git provider and running it through an app's pipeline on that server. Everything happens inside a single Workspace.

Workspaces

A workspace is the top-level container for everything you manage in Devpilot. Each workspace has its own servers, projects, apps, members, integrations, and activity.

Common patterns:

• One workspace per company — All teams and apps live in the same workspace.
• One workspace per client — Agencies keep each client's infrastructure and access isolated.
• One workspace per environment — Some teams split staging and production into separate workspaces.

You can belong to multiple workspaces and switch between them from the dashboard. A workspace is created with a name and an optional logo.

What belongs to a workspace

Projects

A project is a grouping inside a workspace. Projects help you organize related apps — for example, a product with a frontend, a backend API, and a worker.

A project stores a name and an optional logo. It does not have its own server or configuration; it simply groups apps. Create separate projects when apps:

• Belong to different products or services
• Are owned by different teams
• Have different release cadences

Apps

An app is the deployable unit in Devpilot. Each app is created inside a project with a few core fields:

• Name — A human-friendly name for the app.
• Platform — The framework or runtime family the app is built on (for example Laravel, Vanilla PHP, Vanilla JavaScript, Nuxt, React, or Vue).
• Server — The server this app runs on.
• Status — Active or Inactive.

The repository, branch, build configuration, environment variables, and pipeline hooks are set through the deployment wizard rather than on the app form itself. Multiple apps can share a single server, or you can spread apps across different servers.

Servers

A server is a machine — virtual or physical — that runs your apps. Servers enter a workspace in one of two ways.

Provisioned servers

Devpilot talks to a cloud provider's API and creates a new instance for you. Supported providers for provisioning today are:

• AWS (Amazon Web Services)
• Azure (Microsoft Azure)
• GCP (Google Cloud Platform)
• DigitalOcean
• Vultr

Hetzner, Linode, and MTN Cloud are planned providers — they appear in the Integrations page as "Coming soon" and are not yet available for provisioning.

You pick a region, instance type, and image, and Devpilot walks the provision through its stages. Once complete, the server shows up in your server list and is ready to receive deployments.

Connected servers

If you already have a server running somewhere — on a provider not listed above, on bare metal, or in a private data center — you can connect it by providing:

• Host and port
• Username
• Authentication method: a private key (pasted or uploaded), a Devpilot-generated key pair, or a password

Devpilot tests the SSH connection and installs its management agent so deployments can run against the server.

Server tools

Every server in Devpilot has:

• A web terminal for running commands from the browser.
• Monitoring (optional) for CPU, memory, and disk metrics with analytics export.
• Connection status and provisioning status indicators so you can see health at a glance.

Deployments

A deployment is one run of the pipeline for an app. Each deployment captures:

• Commit — The committer, commit id, commit URL, and branch that were deployed.
• Trigger — Who or what started the deployment.
• Timestamps — Started, ended, and total duration.
• Status — Pending, Processing, Completed, Failed, or Cancelled.
• Logs — Full output of every hook that ran.
• Hooks — The exact pipeline that executed, with per-step results.
• Health — Post-deploy health status and whether this version is live.
• Rollback — If the deployment was created as a rollback of another.

How a deployment runs

Deployments go through a series of stages driven by the pipeline of hooks on the app. The five stages, in order, are:

1. pre_execution — Preparation steps that run before anything else.
2. pre_source_control — Last-minute actions before Devpilot fetches your code.
3. post_source_control — Follow-up work right after the code is fetched.
4. post_setup — Runs after the app's runtime is set up (dependencies installed, assets built).
5. post_release — Runs after the new release is made live.

If a hook fails, the deployment stops and is marked Failed. The logs show exactly which hook failed and why.

Rollbacks

A deployment can be rolled back to a previous successful release. The rollback itself is recorded as a new deployment linked to the one it replaced.

Pipelines and Hooks

A pipeline is the ordered list of hooks that runs during a deployment. Each hook has:

• A stage — one of Pre Execution, Pre Source Control, Post Source Control, Post Setup, or Post Release.
• An action type and a name describing what it does.
• A priority that controls ordering within its stage.
• An optional run as user.
• A status (enabled or disabled).

The deployment wizard suggests a pipeline based on what it detected in your repository, and you can then reorder, toggle, add, or edit hooks. Pipelines are stored per app, so subsequent deployments reuse the same configuration unless you change it.

Integrations

Integrations connect a workspace to external services.

Source control integrations

Connect a Git provider so Devpilot can list repositories, fetch branches, and clone code during deployments. Supported providers:

• GitHub
• GitLab
• Bitbucket

Cloud provider integrations

Connect cloud credentials so Devpilot can provision and manage servers through the provider's API. Supported providers:

• AWS
• Azure
• GCP
• DigitalOcean
• Vultr

Integrations are configured at the workspace level. Once connected, members of the workspace can use them subject to their role.

Members and Roles

Devpilot uses role-based access inside each workspace. When you invite someone, you assign them one of the built-in roles:

Role checks apply across the UI and API — actions a member is not permitted to take are hidden or rejected.

How concepts relate to each other

To summarize:

• A Workspace contains servers, projects, integrations, and members.
• A Project belongs to a workspace and groups one or more apps.
• An App belongs to a project, has a platform, and targets a server.
• A Server belongs to a workspace and runs one or more apps.
• A Deployment is one run against an app. It records the commit, hooks, logs, and status.
• A Pipeline of Hooks is attached to the app and runs during each deployment.
• Integrations link the workspace to Git providers and cloud providers.
• Roles control what each member can do inside the workspace.

For a hands-on walkthrough that creates a workspace, server, project, app, and deployment, follow the Quick Start Guide. For account and security setup, see Account Setup.