How to Use Boundary: The Beginner's Guide (First Dev Mode, First SSH Target, and the OIDC Arc)

CodexFuse Team · 2026-11-06T19:01:00.623Z · 24 min read min read

What Is Boundary, Exactly?

Boundary is HashiCorp's identity-based access broker, and learning how to use Boundary means learning to replace VPNs and SSH bastions with per-target sessions granted to a verified identity. A user authenticates once with an identity provider, asks for a session to one specific target, and Boundary proxies just that connection, so the target never needs a public IP and no standing access exists. As of November 2026, this boundary tutorial teaches the final Community Edition release for learning, and points production readers at the current commercial line.

One more thing to settle before you start: CodexFuse offers no Boundary tool, and this guide teaches the self-hosted software itself. You will run it on your own server, in front of your own targets, and only test against targets you own. The Teleport beginner guide covers the certificate-based SSH lane that sits beside this one, and the comparison section near the end draws the line between the two.

This guide exists because the field is older than the current news. The only independent beginner walkthrough anyone has published is 1,384 days old and predates the October 2026 archive, the freshest independent guide is a PostgreSQL-specific setup updated 19 days before this writing, and everything else is vendor docs or a same-author dev.to cluster this guide excludes. The table below shows the field as it stands, and the rest of this guide is the current-version arc none of them gives you.

HashiCorp Boundary is a Go project, and its repository is 2,494 days old, which is 6.83 years. It carries 4,065 stars against 327 forks, which works out to 12.43 stars per fork and an 8.04 percent fork ratio, and its 152 open issues amount to 3.74 open issues per 100 stars. The last Community Edition release is v0.21.3 from 2026-04-30, 190 days before this writing, and the last push to the repository was 2026-10-09, 28 days before this writing, when HashiCorp archived it.

Read This First: Community Edition Was Archived in October 2026

HashiCorp archived Community Edition in October 2026, and that fact shapes every step that follows. HashiCorp archived the hashicorp/boundary repository on 2026-10-09, 28 days before this writing, and the repository README now says no new Boundary CE releases, maintenance updates, bug fixes, or security patches are currently planned. The repository is read-only, it accepts no new issues or pull requests, and the last release, v0.21.3, will never get a patch.

The archive reversed a promise HashiCorp made six months earlier. In April 2026 a Boundary product manager wrote that the team would continue to support Community Edition with bug fixes and security patches, and in September a second product manager repeated that support would continue. The October update struck that promise through and said all research and development resources were diverted to the commercial editions, so do not trust any guide that still quotes the April promise as current.

Do not mix up the two version lines, because they now move on separate tracks. Community Edition ends at v0.21.3, and the commercial line, HCP Boundary and Boundary Enterprise, is at 1.1.0, released 2026-10-26, 11 days before this writing. The table below keeps them apart.

Version 1.1.0 is the current commercial release, and its headline features are app tokens for machine-to-machine authentication and a Boundary MCP server in public preview. It also resolves Azure Entra ID group-overage claims through Microsoft Graph, discovers EC2 instances across AWS accounts, caches RDP session-recording video on workers, and evaluates OIDC managed-group filters concurrently. The release notes also warn that upgrading to 1.1.0 from 0.20.5, 0.21.5, 0.21.6, 1.0.2, or 1.0.3 can skip required database migrations, and point at 1.1.1 instead.

The last Community Edition release was itself a security fix. HCSEC-2026-11, published 2026-05-04, 186 days before this writing, disclosed a denial-of-service flaw in Boundary workers during the TLS handshake, tracked as CVE-2026-7776, and fixed it in 0.21.3, 0.20.3, and 0.19.5. IBM closed its acquisition of HashiCorp on 2025-02-27, 617 days before this writing, for 6.4 billion dollars, and IBM lists support for the 0.21 line through 2027-12-31, the 0.20 line through 2027-09-30, and the 0.19 line through 2027-07-31.

The numbers in this section were computed from the repository and release dates on 2026-11-06, and the block below shows the arithmetic.

from datetime import date
ref = date(2026, 11, 6)
repo_created = date(2020, 1, 8)
print('repo age days:', (ref - repo_created).days)
print('repo age years:', round((ref - repo_created).days / 365.25, 2))
print('stars per fork:', round(4065 / 327, 2))
print('fork ratio percent:', round(327 / 4065 * 100, 2))
print('open issues per 100 stars:', round(152 / 4065 * 100, 2))
print('v0.21.3 days before this writing:', (ref - date(2026, 4, 30)).days)
print('last push days before this writing:', (ref - date(2026, 10, 9)).days)
print('1.1.0 days before this writing:', (ref - date(2026, 10, 26)).days)
print('1.0.0 GA days before this writing:', (ref - date(2026, 6, 30)).days)
print('amireslampanah guide days old:', (ref - date(2023, 1, 22)).days)
print('IBM acquisition days before this writing:', (ref - date(2025, 2, 27)).days)
print('HCSEC-2026-11 days before this writing:', (ref - date(2026, 5, 4)).days)

How Boundary Works: Controller, Worker, and Target

Boundary has three moving parts, and the mental model is one sentence long. A controller decides who may connect, a worker carries the connection, and a target is the thing you connect to. The user never talks to the target directly, and the target never needs a public IP, because the worker is the only component that ever sees the target's real address.

Scopes organize everything, and they nest three levels deep. The global scope holds organizations, each organization holds projects, and targets, host catalogs, and roles live inside projects. Users, groups, and roles attach at the scope that fits, and permissions are a composable allow-only model, so a grant says exactly which actions on which resource types are allowed and nothing else.

A target is not a server, it is a permission to reach a service. A target names a default port and a set of hosts, and when a user asks for a session Boundary checks the grants, opens a proxied connection through a worker, and logs the session. The user gets a local port on their own machine that forwards to the target, and the connection dies when the session ends or its time limit runs out.

Session recording is enterprise-only, so do not expect keystroke or video recording in Community Edition. Community Edition keeps the audit log and the session lifecycle events, which show who connected to what and when, but recording SSH and RDP sessions needs HCP Boundary or Boundary Enterprise. Session controls such as connection limits and maximum session seconds work the same in every edition.

What You Need Before You Install

You need five things, and none of them is exotic. A machine to run Boundary on, a target host you own, Docker installed for dev mode, the Boundary CLI, and an identity provider for real users later. Dev mode needs Docker because it spins up a Postgres container for its ephemeral database, and that is the only job Docker does here.

There is no official Boundary Docker image, so do not go looking for a docker pull command for Boundary itself. HashiCorp ships binaries and packages, not a container, and the only container involved is the Postgres database that dev mode starts for you. If a guide tells you to run Boundary in Docker, it is teaching something the vendor never published.

Pick the edition before you install, because the choice is now load-bearing. A boundary self hosted install for learning runs on the final Community Edition release, 0.21.3, with the archive warning in mind, and anything production-facing runs on HCP Boundary or Boundary Enterprise 1.1.0. The install section below gives both routes, and the self-hosting section near the end explains what production actually needs.

Install Boundary on macOS, Linux, and Windows

Install the CLI first, because every later step runs through it. macOS uses Homebrew, Debian and Ubuntu use HashiCorp's apt repository, and every platform can also use a plain binary zip. The Docker beginner guide covers installing Docker itself if it is new to you, since dev mode needs it in the next section.

On macOS, tap the HashiCorp repository first, then install the Community Edition binary. The Enterprise binary installs from the same tap under the name boundary-enterprise, and the two never mix on one machine in this guide.

brew tap hashicorp/tap
brew install hashicorp/tap/boundary
boundary version

On Debian or Ubuntu, add HashiCorp's signing key and repository, then install the package. The package also creates a dedicated boundary system user, a systemd unit, and example configuration files under /etc/boundary.d, which the production section uses later.

curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update
sudo apt install -y boundary
boundary version

Verify the binary before you trust it. Boundary publishes SHA256 checksums for every release zip, and the version command prints the build you installed. If it prints 0.21.3, you are on the final Community Edition release, and if it prints 1.1.0, you are on the commercial line.

Start Dev Mode and Log In for the First Time

Dev mode is testing-only, never production, and it is the fastest honest way to learn Boundary. One command starts an ephemeral controller and worker plus a Postgres database, prints the admin login, and creates a small set of ready-made resources. Nothing persists when you stop it, the database URL uses a random port, and the passwords are the well-known defaults, so never expose a dev-mode instance to a network.

The whole first run of boundary dev mode takes seven steps, and the list below is the snippet-shaped version you can follow top to bottom.

1. Install the Boundary CLI and Docker, then confirm both answer to version checks.
2. Run boundary dev in a terminal and leave it running.
3. Copy the admin login name and password from the printed output.
4. In a second terminal, run boundary authenticate and sign in as admin.
5. List the pre-created targets to see the two demo targets.
6. Connect to the first target with boundary connect ssh.
7. Stop dev mode with Ctrl-C when you are done, and know nothing persists.

Dev mode prints a configuration block when it starts, and the addresses in it never change between runs. The controller API listens on 127.0.0.1:9200, the worker proxy on 127.0.0.1:9202, and the cluster address on 127.0.0.1:9201, while the database URL points at a Postgres container on a random local port.

boundary dev
# Controller API: http://127.0.0.1:9200
# Worker proxy:  http://127.0.0.1:9202
# Generated Admin Login Name: admin
# Generated Admin Password:   password
# Generated Unprivileged Login Name: user
# Generated Unprivileged Password:   password

Authenticate with the short form, which uses the primary password auth method that dev mode pre-creates. The token is saved to your system password store on macOS and Windows, and on other Unix systems Boundary falls back to pass, the GPG-encrypted store, when the desktop secret service is missing.

boundary authenticate
# prompts for login name, then password (both hidden)
# dev defaults: admin / password
boundary authenticate password -login-name=admin -password password -auth-method-id=ampw_1234567890

Dev mode pre-creates a full set of demo resources with fixed IDs, and the list below is what you will see when you explore. The organization scope is o_1234567890, the project scope is p_1234567890, the password auth method is ampw_1234567890, the static host catalog is hcst_1234567890, and the two TCP targets are ttcp_1234567890 for a direct address and ttcp_0987654321 for a host set. You can pass flags to boundary dev to randomize or override these IDs, and the dev command help lists them.

Create Your First SSH Target

A target is built from four resources, and the order matters. You create a host catalog, add a host to it, group hosts into a host set, and then create a target that points at the host set. The target names a default port, and for SSH that port is 22, so a boundary ssh session opens exactly the service you named and nothing else.

The commands below create a static catalog, one host, one host set, and one TCP target for a database server, and you replace the example address with your own host. Each command prints the ID of the resource it created, so use those IDs in the next command, and the scope-id flag is the project scope that owns the target.

boundary host-catalogs create static -name "prod-hosts" -scope-id p_1234567890
boundary hosts create static -host-catalog-id YOUR_CATALOG_ID -address "10.0.5.10" -name "db-prod-1"
boundary host-sets create static -host-catalog-id YOUR_CATALOG_ID -name "prod-dbs"
boundary host-sets add-hosts -id YOUR_SET_ID -host YOUR_HOST_ID
boundary targets create tcp -name "prod-postgres" -default-port 5432 -scope-id p_1234567890 -host-source-ids YOUR_SET_ID

The same resources exist in the Admin UI, and the UI is the kinder way to learn the model. The controller serves the Admin UI on port 9200, you sign in with the same admin login, and scopes, host catalogs, host sets, and targets all appear as pages. The CLI is faster once you know the model, and the UI is clearer while you are still learning it.

Give the target a name your team will understand, because names are what users see. A target called prod-postgres tells a user exactly what they are opening, and a target called ttcp-1 tells them nothing. The target list is the menu your users choose from, so name every entry like a menu item.

Connect to a Target: What Happens Behind the Scenes

Connecting is one command, and the session that follows is the whole point of Boundary. You list your targets, pick one, and Boundary opens a local port on your machine that forwards through a worker to the target. Your SSH client talks to localhost, the worker talks to the target, and you never learn the target's real IP address.

The connect commands below cover the three shapes you will use most. Plain boundary connect opens a raw TCP proxy, boundary connect ssh spawns your SSH client with the right arguments, and boundary connect postgres spawns psql, so each tool gets the connection it expects.

boundary targets list
boundary connect -target-id ttcp_1234567890
boundary connect ssh -target-id ttcp_1234567890
boundary connect ssh ssh.boundary.dev
boundary connect ssh ssh.boundary.dev -username james
boundary connect postgres -target-id ttcp_1234567890

A dedicated SSH target type also exists, and it is worth knowing about. The HCP tutorial walks through SSH with a generic TCP target on port 22, and notes the dedicated SSH type as the alternative, so either shape reaches the same server. Target aliases add a friendlier name on top: dev mode gives its localhost target the alias ssh.boundary.dev, so boundary connect ssh ssh.boundary.dev reaches your own machine, and sessions last 8 hours by default, which is 28,800 seconds.

Sessions end in three ways, and all three leave a record. You close the connection, the session hits its maximum seconds, or an admin cancels it from the sessions page or the CLI. The audit log keeps the session lifecycle events, which is how you answer who connected to what and when, even in Community Edition.

Add Real Users with OIDC

Passwords are for learning, and OIDC is for real users. An OIDC auth method lets Boundary delegate logins to an identity provider, so your team signs in with the accounts they already have and Boundary never stores their passwords. This section creates the boundary oidc auth method in three moves: register Boundary in the provider, create the method, and activate it.

The Authentik beginner guide covers running the identity provider itself, and this section wires it into Boundary as the OIDC source.

Register Boundary as an application in your provider first, and use the callback URL below with your own Boundary address. The provider gives you a client ID and a client secret, and the signing algorithm is RS256, which is the default Boundary expects.

boundary auth-methods create oidc -name "Authentik" -issuer "https://auth.example.com/application/o/boundary/" -client-id "YOUR_CLIENT_ID" -client-secret "YOUR_CLIENT_SECRET" -signing-algorithms "RS256" -api-url-prefix "https://boundary.example.com"

A new OIDC method starts inactive, and that trips up first-time admins. Activate it as Active Public to list it on the login page, or Active Private to keep it usable but unlisted, and then make it primary for the scope, or first-login user creation fails. Managed groups can auto-assign roles from the provider's groups, and version 1.1.0 evaluates those filters concurrently and resolves Azure group-overage claims through Microsoft Graph.

Two issuer details catch people out, and both are in the vendor docs. An Auth0 issuer needs a trailing slash, and an Okta issuer must not have one, so copy the issuer URL exactly as the provider prints it. Authentik, Okta, Microsoft Entra ID, and Google all work as providers, because any OIDC provider can fill this role, and none of them is a rival to Boundary.

Let Vault Mint Short-Lived Credentials

The strongest Boundary feature is the one that removes passwords from human hands entirely. With Vault wired in as a credential store, Boundary asks Vault for a fresh credential when a session starts, injects it into the proxied connection, and Vault revokes it when the session ends. The human never sees the password, so there is nothing to leak, reuse, or write down.

The wiring is three commands, and each one names the next resource. A credential store points at Vault, a credential library names the Vault path that mints the credential, and the target takes the library as its brokered credential source.

boundary credential-stores create vault -address "https://vault.example.com" -token "YOUR_VAULT_TOKEN"
boundary credential-libraries create vault -vault-path "database/creds/readonly-role" -credential-store-id "YOUR_STORE_ID"
boundary targets add-credential-sources -id "YOUR_TARGET_ID" -brokered-credential-source "YOUR_LIBRARY_ID"

One edition note belongs here, because the install page lists credential injection among the Enterprise capabilities. The Vault store and library commands are the documented wiring, and the credential flow is the architecture Boundary is built around, so verify the edition behavior on your own install before depending on it in production. The vendor also publishes a Vault credential-brokering quickstart that runs about twenty minutes, and it is the best next step once the basic flow works.

Boundary vs VPN vs Teleport vs Pomerium

Boundary is not a VPN, and the difference is the whole pitch. A VPN gives a connected user reach to a whole network segment, and everyone inside the tunnel trusts everyone else. Boundary gives a verified user a session to one specific service, and nothing else, so the blast radius of a compromised account is one target instead of one network.

Teleport is the closest sibling, and the mechanism is the difference. Teleport issues short-lived certificates to users, devices, and machines and connects them directly, while Boundary brokers each session through a worker and can mint credentials from Vault. The Vouch Proxy beginner guide covers the auth-proxy lane, which gates web apps with one login, and that is a third shape again: a login gate, not an infrastructure broker.

Pomerium works at a different layer, and that decides which tool fits. Pomerium verifies every HTTP request at layer 7, which suits web apps, while Boundary brokers TCP sessions, which suits SSH, RDP, and databases. Authentik is not a rival at all, because it is the identity provider Boundary delegates logins to, and the same is true of Okta, Auth0, and Microsoft Entra ID, so all three sell zero trust access and the honest question is which shape your team actually needs.

The rival comparison pages are marketing, so read them that way. Teleport's page claims Boundary still holds credentials during sessions and logs only session metadata, and Pomerium's page claims Boundary verifies only at session start and needs clients on user devices. Those are the rivals' claims, not neutral facts, and the neutral line is simpler: different mechanisms, different layers, different jobs.

Self-Hosting Boundary Beyond Dev Mode

Production Boundary looks nothing like dev mode, and the shape is three controllers plus three workers. The same binary plays either role depending on its HCL configuration, the state lives in PostgreSQL, and the encryption keys come from KMS blocks for root, worker authentication, and recovery. You initialize the database once with boundary database init, then start each node with boundary server and its config file.

The VPS hosting guide covers picking the server itself, and Boundary adds three requirements on top of it. The controllers need a reachable PostgreSQL database, the workers need egress access to the controller and to the targets, and the targets need no inbound access at all, because workers only ever connect outward. That last point is why Boundary needs no ingress firewall rules and no bastion host.

HCP Boundary is the managed alternative, and it keeps the same model with HashiCorp running the control plane. You deploy a cluster from the HCP portal, install self-managed workers in your own network, and use the same CLI and Desktop clients. The forum post that announced the archive also mentions a PayGo subscription with a 500-dollar trial credit for teams that are unsure, and that figure comes from HashiCorp's own post, not from a price list.

If you self-host Community Edition today, plan the exit now. The binaries remain available, and IBM lists support for the 0.21 line through 2027-12-31, but no new release is currently planned, so a security flaw found later may have no patch coming. A community fork named Threshold has appeared, and its release status had not been independently verified at the time of writing, so treat it as a project to watch rather than a migration plan.

Sources

HashiCorp's own documentation carries this guide: the get-started-community tutorial, the install page, the dev-mode and run-and-login docs, the release notes and change tracker, the VPN overview page, and the OIDC guides for Auth0 and Okta. The GitHub API supplied the repository facts, including the archived flag, the 4,065 stars, the 327 forks, the 152 open issues, and the v0.21.3 release date. The HashiCorp Discuss thread on the Community Edition's long-term scope supplied the April promise, the September repetition, and the October archive decision, including the README wording quoted above.

The independent field was checked the same day: Amir Eslampanah's January 2023 guide, a fresh Medium guide on PostgreSQL targets updated 19 days before this writing, and a DZone walkthrough from 1,312 days before this writing. The Teleport and Pomerium comparison pages were used only for the rivals' own claims, and both are attributed as marketing. The IBM newsroom supplied the acquisition close date and price, the IBM support page supplied the 0.19, 0.20, and 0.21 support dates, and a DevOps Digest article supplied the Business Source License date.

Two dev.to pieces by one author were excluded as a same-author spam cluster, and neither is cited anywhere in this guide. The Threshold fork is mentioned only as a project to watch, because its release status had not been independently verified at the time of writing. The 1.1.1 upgrade warning is reported without a date, because no 1.1.1 release date was verified, and no official container image for Boundary was found, so none is claimed.

Frequently Asked Questions

Is HashiCorp Boundary still free?

The Community Edition binaries remain available for existing self-managed use, and they cost nothing to download. But the edition is archived, with no new releases, maintenance updates, bug fixes, or security patches currently planned, so free now means unmaintained. New deployments should scope against HCP Boundary or Boundary Enterprise, which are the editions HashiCorp still develops.

Is Boundary a VPN?

No, it is not a VPN. A VPN connects you to a whole network segment, while Boundary grants a verified identity a session to one specific target, and nothing else. It can replace a VPN for infrastructure access, or sit beside an existing corporate VPN for privileged networks.

What is the difference between Boundary and Teleport?

Teleport issues short-lived certificates and connects users directly, while Boundary brokers each session through a worker and can mint credentials from Vault. Teleport is the certificate-based SSH lane, and Boundary is the identity-aware session-broker lane. The two solve the same problem with different mechanisms, so pick by mechanism, not by marketing.

Can I run Boundary in Docker?

HashiCorp ships no container image for Boundary itself, so do not look for a docker pull command for it. Docker's job here is different: dev mode needs Docker installed because it starts its Postgres database in a container. Install Boundary from Homebrew, apt, or a binary zip, and let Docker serve only the dev-mode database.

What do I need before my first target?

You need the Boundary CLI, Docker running for dev mode, and a target host you own, with SSH on port 22. Dev mode gives you two demo targets to practice on, and your first real target needs only a host catalog, a host, a host set, and the target itself. Add an identity provider later, when passwords stop being enough.