macgo

Overview ¶

Package macgo provides seamless macOS application bundle creation with permissions and entitlements.

macgo enables Go programs to integrate with macOS security features by automatically creating app bundles with proper structure, Info.plist, entitlements, and code signing. This allows Go applications to request system permissions (camera, microphone, files, etc.) just like native macOS applications.

Quick Start ¶

The simplest way to use macgo is with the Request function:

err := macgo.Request(macgo.Camera)
if err != nil {
    log.Fatal(err)
}
// Camera permission granted, proceed with camera access

Request multiple permissions at once:

err := macgo.Request(macgo.Camera, macgo.Microphone, macgo.Files)
if err != nil {
    log.Fatal(err)
}

Configuration ¶

For more control, use the Config struct with builder methods:

cfg := macgo.NewConfig().
    WithAppName("MyApp").
    WithBundleID("com.example.myapp").
    WithPermissions(macgo.Camera, macgo.Microphone).
    WithAdHocSign().
    WithDebug()

err := macgo.Start(cfg)
if err != nil {
    log.Fatal(err)
}

Available Permissions ¶

• Camera: access to camera
• Microphone: access to microphone
• Location: access to location services
• ScreenRecording: access to screen recording
• Accessibility: access to Accessibility features (e.g. input simulation)
• Files: access to user-selected files
• Network: network client/server access
• Sandbox: enable app sandbox with restricted file access

Launch Modes ¶

macgo supports three launch strategies:

Bundle mode (default): creates a .app bundle, relaunches via LaunchServices, and forwards I/O. Required for TCC-dialog permissions (Camera, Microphone, Location).

Single-process mode: codesigns the binary in-place, re-execs for the kernel to pick up new entitlements, then calls setActivationPolicy. No bundle, no child process, no I/O forwarding. Only works for entitlement-only permissions (Accessibility, Virtualization, Network). Enable via Config.WithSingleProcess or MACGO_SINGLE_PROCESS=1.

The internal/launchservices package provides a standalone pure Go replacement for /usr/bin/open (available as cmd/lsopen), but is not used by the default bundle launch path due to run loop constraints in library contexts.

Code Signing ¶

macgo supports multiple signing approaches:

Ad-hoc signing for development:

cfg := macgo.NewConfig().WithAdHocSign()

Automatic Developer ID detection:

cfg := macgo.NewConfig().WithAutoSign()

Specific signing identity:

cfg := macgo.NewConfig().WithCodeSigning("Developer ID Application: Your Name")

Environment Variables ¶

All configuration can be driven by environment variables, which are read by Config.FromEnv. Variables are grouped by category below.

Application identity:

MACGO_APP_NAME            Application display name
MACGO_APP_NAME_PREFIX     Prefix prepended to app names (e.g. "Dev-")
MACGO_BUNDLE_ID           Bundle identifier (e.g. "com.example.myapp")
MACGO_BUNDLE_ID_PREFIX    Prefix prepended to bundle IDs (e.g. "test.")

Permissions (set to "1" to enable):

MACGO_CAMERA              Request camera access
MACGO_MICROPHONE          Request microphone access
MACGO_LOCATION            Request location services access
MACGO_SCREEN_RECORDING    Request screen recording access
MACGO_FILES               Request user-selected file access
MACGO_NETWORK             Request network client access
MACGO_SANDBOX             Enable app sandbox

Code signing:

MACGO_AD_HOC_SIGN         Ad-hoc sign the bundle (set to "1")
MACGO_AUTO_SIGN           Auto-detect Developer ID certificate (set to "1")
MACGO_CODE_SIGN_IDENTITY  Specific signing identity string

Launch behavior (set to "1" unless noted):

MACGO_SINGLE_PROCESS      Single-process mode: codesign + re-exec, no bundle
MACGO_FORCE_DIRECT        Force direct binary execution (skip LaunchServices)
MACGO_FORCE_LAUNCH_SERVICES  Force LaunchServices even when not needed
MACGO_NO_RELAUNCH         Disable automatic relaunch entirely
MACGO_OPEN_NEW_INSTANCE   Set to "0" to disable -n flag for open command

Bundle and debugging:

MACGO_DEBUG               Enable debug logging to stderr (set to "1")
MACGO_KEEP_BUNDLE         Preserve temporary bundle after execution (set to "1")
MACGO_ICON                Path to .icns file for the app icon
MACGO_PROVISIONING_PROFILE  Path to provisioning profile to embed
MACGO_RESET_PERMISSIONS   Reset TCC permissions before requesting (set to "1")

Development:

MACGO_DEV_MODE            Dev mode: signed wrapper exec's the source binary (set to "1")
MACGO_TTY_PASSTHROUGH     Pass TTY device to child process (experimental, set to "1")

Internal (set by macgo, not typically set by users):

MACGO_STDIN_PIPE          Path to stdin named pipe (child reads from parent)
MACGO_STDOUT_PIPE         Path to stdout named pipe (child writes to parent)
MACGO_STDERR_PIPE         Path to stderr named pipe (child writes to parent)
MACGO_CONTROL_PIPE        Path to control FIFO (child writes PID for signal forwarding)
MACGO_CWD                 Original working directory to restore in child
MACGO_BUNDLE_PATH         Path to the .app bundle
MACGO_ORIGINAL_EXECUTABLE Path to the original binary before bundle copy
MACGO_SINGLE_PROCESS_ACTIVE  Sentinel: set to "1" after single-process re-exec

Bundle Structure ¶

macgo creates a standard macOS app bundle:

MyApp.app/
├── Contents/
│   ├── Info.plist
│   ├── MacOS/
│   │   └── MyApp
│   ├── Resources/
│   └── _CodeSignature/

Bundle ID Generation ¶

macgo generates bundle IDs from your Go module path:

github.com/user/project     → com.github.user.project.appname
gitlab.com/org/tool         → com.gitlab.org.tool.appname
example.com/app             → com.example.app.appname
Private/custom modules      → io.username.appname

Auto Packages ¶

Import auto packages for pre-configured setups:

import (
    _ "github.com/tmc/macgo/auto/media"   // Camera + Microphone
    _ "github.com/tmc/macgo/auto/files"   // File access
    _ "github.com/tmc/macgo/auto/adhoc"   // Ad-hoc signing
    "github.com/tmc/macgo"
)

func main() {
    macgo.Request()
}

Cleanup ¶

Cleanup is no longer required. FIFO-based I/O forwarding uses pipe EOF as the exit signal, so no explicit cleanup call is needed. The function is retained as a no-op for backward compatibility.

TCC Integration ¶

macgo integrates with macOS TCC (Transparency, Consent, and Control) to:

• Generate proper entitlements for requested permissions
• Handle permission prompts automatically
• Reset permissions for testing (when requested)
• Support both sandboxed and non-sandboxed applications

Package macgo provides simple macOS app bundle creation and TCC permission management.

macgo enables Go applications to request macOS system permissions (camera, microphone, files, etc.) by automatically creating app bundles with proper entitlements and handling the relaunch process when necessary.

Usage ¶

To correctly use macgo, you must call macgo.Start() or macgo.Request() at the very beginning of your main() function, before any other logic or background goroutines are started.

1. Basic Usage (One-Liner)

func main() {
    // Request permissions immediately.
    // If the app is not in a bundle, this will create one and relaunch the app.
    if err := macgo.Request(macgo.Camera, macgo.Microphone); err != nil {
        log.Fatal(err)
    }

    // Your application logic starts here...
}

2. Advanced Usage (Configuration)

func main() {
    cfg := &macgo.Config{
        AppName:     "MyApp",
        Permissions: []macgo.Permission{macgo.Camera, macgo.Files},
        Debug:       true, // Enable debug logging to stderr
    }

    // Initialize macgo. This logic handles the process lifecycle.
    // If a relaunch is needed, Start will exit the current process.
    if err := macgo.Start(cfg); err != nil {
        log.Fatal(err)
    }

    // Your application logic starts here...
}

How it Works ¶

When macgo.Start() is called:

1. It checks if the program is running inside a valid macOS App Bundle.
2. If NOT, it creates a temporary App Bundle in /tmp with the requested entitlements.
3. It relaunches the current executable *inside* that bundle using `open`.
4. It transparently forwards stdin/stdout/stderr from the bundled process to your terminal.
5. The original process exits.
6. If ALREADY inside a bundle (the relaunched process), Start() simply returns nil, allowing your main() function to proceed with the requested permissions.

Important Notes ¶

• macgo.Start() MUST be called early in main().
• Do not rely on init() functions for logic that depends on permissions, as they run before main.
• macgo preserves exit codes and terminal I/O.

package main

import (
	"github.com/tmc/macgo"
)

func main() {
	// macgo automatically generates meaningful bundle IDs based on your Go module
	// Examples of automatic bundle ID generation:
	//
	// Module: github.com/user/myproject -> Bundle ID: com.github.user.myproject.appname
	// Module: gitlab.com/company/tool   -> Bundle ID: com.gitlab.company.tool.appname
	// Module: example.com/service       -> Bundle ID: com.example.service.appname
	// No module info available          -> Bundle ID: dev.username.appname (or local.app.appname)
	//
	// This replaces the old generic "com.macgo.*" format with meaningful,
	// unique identifiers that reflect your actual project.

	cfg := &macgo.Config{
		AppName: "MyTool",
		// BundleID is automatically inferred from Go module if not specified
		Permissions: []macgo.Permission{macgo.Files},
	}

	err := macgo.Start(cfg)
	if err != nil {
		// Handle error
		return
	}
	// Bundle ID automatically generated based on module path
}

package main

import (
	"os"

	"github.com/tmc/macgo"
)

func main() {
	// Environment variables that control macgo behavior:
	// MACGO_NO_RELAUNCH=1           - Skip bundle creation and relaunch
	// MACGO_DEBUG=1                 - Enable debug logging
	// MACGO_RESET_PERMISSIONS=1     - Reset TCC permissions using tccutil
	// MACGO_APP_NAME=MyApp          - Set application name
	// MACGO_APP_NAME_PREFIX=Dev-    - Add prefix to all app names
	// MACGO_BUNDLE_ID=com.example   - Set bundle identifier
	// MACGO_BUNDLE_ID_PREFIX=dev    - Add prefix to all bundle IDs
	// MACGO_KEEP_BUNDLE=1           - Preserve bundle after execution
	// MACGO_CODE_SIGN_IDENTITY=xyz  - Set code signing identity
	// MACGO_AUTO_SIGN=1             - Enable automatic code signing
	// MACGO_AD_HOC_SIGN=1           - Use ad-hoc code signing
	// MACGO_CAMERA=1                - Request camera permissions
	// MACGO_MICROPHONE=1            - Request microphone permissions
	// MACGO_LOCATION=1              - Request location permissions
	// MACGO_FILES=1                 - Request file access permissions
	// MACGO_NETWORK=1               - Request network permissions
	// MACGO_SANDBOX=1               - Enable app sandbox

	// Example: Reset permissions before requesting new ones
	_ = os.Setenv("MACGO_RESET_PERMISSIONS", "1")
	_ = os.Setenv("MACGO_DEBUG", "1")
	defer func() {
		_ = os.Unsetenv("MACGO_RESET_PERMISSIONS")
		_ = os.Unsetenv("MACGO_DEBUG")
	}()

	err := macgo.Request(macgo.Camera)
	if err != nil {
		// Handle error
		return
	}
	// Permissions reset and then requested
}