GitHub - highpost/tailscale-macos-vm: Using Tailscale with an OrbStack VM on macOS · GitHub

Skip to content

Navigation Menu

Toggle navigation

Sign in

Appearance settings

PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

highpost

/

tailscale-macos-vm

Public

Notifications
You must be signed in to change notification settings

Fork
0

Star
4

Code

Issues
0

Pull requests
0

Actions

Projects

Security and quality
0

Insights

Additional navigation options

Code

Issues

Pull requests

Actions

Projects

Security and quality

Insights

highpost/tailscale-macos-vm

 mainBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History1 Commit1 CommitREADME.mdREADME.md  build.shbuild.sh  cleanup.shcleanup.sh  dev-server.ymldev-server.yml  run.shrun.sh  store-ts-key-keychain.shstore-ts-key-keychain.sh  View all filesRepository files navigationREADMEUsing Tailscale with an OrbStack VM on macOS
This repository demonstrates how to use OrbStack on macOS to provision an Ubuntu virtual machine (VM), and then add it to your tailnet.
Unlike minimal container runtimes that lack native kernel modules, OrbStack provides a fully capable Linux kernel environment. This allows Tailscale to leverage standard kernel networking (/dev/net/tun) rather than relying on userspace-networking workarounds.
OrbStack first spins up a temporary VM instance which allows cloud-init to pull its configuration from dev-server.yml and then stops the VM. Then OrbStack wakes up the pre-configured VM, adds it to your tailnet using an auth key and enables Tailscale SSH. You can then SSH to your VM from anywhere, without exposing host ports.
This example also demonstrates a macOS-specific method for securely storing your Tailscale auth key in Apple Keychain. Due to macOS security sandbox restrictions, the guest VM cannot directly execute security find-generic-password to pull secrets from the host. Instead, the credential must be injected from the host macOS environment during provisioning, as shown in run.sh.
Modify access controls
Before launching the VM, configure your Tailscale Access Control Lists (ACLs) to handle the automated registration and permissions.
Create a tag
Go to Access controls > Tags and define a server tag:

Tag name: myservers
Tag owners: your-email@example.com

Modify the Tailscale SSH access controls
Go to Access controls > Tailscale SSH and ensure your policy permits access to the tagged servers and specified users:
{
"action": "accept",
"src": ["autogroup:admin"],
"dst": ["tag:myservers"],
"users": ["player1", "player2"]
}

Add your new tag ("myservers") to the Destination (dst) array.
Add the Linux usernames defined in your cloud-config ("player1", "player2") to the Destination users (users) array.
Change "action" from "check" to "accept" for seamless SSH access.

Create a Tailscale auth key

Generate an auth key via the Tailscale Admin Keys panel with these configurations:

Reusable: Enabled
Pre-authorized: Enabled
Tags: Choose the newly created tag: tag:myservers

Store the newly created auth key in Keychain:

./store-ts-key-keychain.sh

(Note: This creates an entry named tailscale-auth-key-dev-server in your Keychain).
Build and provision the VM
./build.sh

Start the VM and add it to your tailnet
./run.sh

Connect to the VM
Once run.sh finishes authenticating the machine, you can connect directly over your tailnet using Tailscale SSH or jump straight into the machine locally via OrbStack:

MagicDNS name: ssh player1@dev-server
built-in local SSH proxy: ssh player1@dev-server@orb
CLI: orb -m dev-server

Example: git
Once Tailscale SSH is setup correctly, it's simple to use git remotely. Let's
assume that we have a git repo on dev-server. We can simply clone it directly without any extra authentication:
git clone player1@dev-server:~/my-proj

Files

dev-server.yml: A cloud-init recipe that specifies environment configurations, system locales, default development packages, user access profiles and installation tasks for the Tailscale engine.
build.sh: Builds and provisions an Ubuntu 25.10 environment using the cloud.init configuration in dev-server.yml.
run.sh: Pulls the auth key from Keychain and brings up the Tailscale interface (tailscale up) inside the VM with SSH enabled.
cleanup.sh: Fully tears down the setup. It logs out the VM from your tailnet, destroys the OrbStack instance, and wipes the auth key from Keychain.
store-ts-key-keychain.sh: Copies the auth key from the system clipboard and stores it in Keychain.

About

Using Tailscale with an OrbStack VM on macOS

Resources

Readme

Uh oh!

There was an error while loading. Please reload this page.

Activity
Stars

4
stars
Watchers

0
watching
Forks

0
forks

Report repository

Releases
No releases published

Packages
0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Shell
100.0%

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

This repository demonstrates a method for integrating Tailscale networking with an OrbStack virtual machine running on macOS to establish secure remote access. The core technical advantage lies in OrbStack's ability to provide a fully capable Linux kernel environment, which allows Tailscale to utilize standard kernel networking facilities, such as /dev/net/tun, thus bypassing reliance on less secure userspace networking methods. The provisioning process involves spinning up a temporary virtual machine instance, utilizing cloud-init to load configuration settings from a designated file, and then bringing the pre-configured VM online. This workflow is orchestrated to add the VM to the user's Tailnet using an authentication key and enable Tailscale SSH, allowing users to connect to the VM remotely without exposing the host machine's ports.

A critical element of this setup involves secure handling of authentication credentials. Due to macOS security sandbox restrictions, the guest VM cannot directly access secrets stored on the host system, such as the Tailscale authentication key. Consequently, secrets must be injected from the host macOS environment during the provisioning phase, as demonstrated by the execution of scripts like run.sh. The security mechanism leverages the Apple Keychain to store the Tailscale auth key securely.

Establishing access requires careful configuration of Tailscale Access Control Lists and SSH permissions. The process begins by defining a custom tag, such as myservers, within Tailscale Access Controls. Subsequently, the Tailscale SSH policies must be modified to explicitly permit access to servers tagged with this new tag for specified users. This involves setting the action from check to accept and mapping desired usernames to the destination users, ensuring that only authorized entities can establish SSH sessions.

The operational workflow involves a sequence of script executions managed by files such as build.sh, run.sh, and cleanup. The build script utilizes the cloud-init configuration to provision an Ubuntu environment, followed by the run script, which retrieves the stored authentication key from the Keychain and initializes the Tailscale interface within the virtual machine, enabling SSH. This setup facilitates seamless remote interaction, exemplified by allowing a user to clone a repository directly on the remote server via Tailscale SSH.

The repository provides several supporting files detailing these steps, including dev-server.yml, which defines environment configurations and installation tasks, build.sh for environment provisioning, run.sh for VM startup and network integration, cleanup.sh for complete resource teardown, and store-ts-key-keychain.sh for securely storing the necessary authentication key in the system Keychain. The overall objective is to create a reproducible and secure mechanism for deploying and securely connecting to remote Linux environments on macOS via Tailscale.