百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
O

obscuravpn-client

> 编程语言
开源

Obscura VPN Rust 库和应用程序(目前仅限 macOS)

386 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

Obscura VPN Rust 库和应用程序(目前仅限 macOS)

Obscura VPN Client

Obscura VPN library, CLI client, and App

Support

No support is provided for this code directly. However, if you are experiencing issues with your Obscura VPN service please contact .

Contributions

At this time we are unable to accept external contributions. This is something that we plan to resolve soon. However until we finish the paperwork we are unable to look at any patches and will close all PRs without looking at them.

Conventions, terminology, and intended behavior are documented in the docs directory. Contributions must align with these documents or change them accordingly.

macOS App

On macOS the app installs and manages a network extension (system extension). The network extension manages the virtual device and maintains the tunnel using the Rust code as library.

Setup

  1. Setup Nix
  2. Install dependencies: nix-env -iA nixpkgs.{cmake,rustup}
  3. Open the main Xcode project
    bash
    nix develop --print-build-logs --command just xcode-open
  4. In Xcode, login with an account with membership in "Sovereign Engineering Inc."
    • In top status bar go to Xcode > Settings > Apple Accounts > Sign in
  5. Register development machine in Apple Developer portal (can be done in Xcode)
    1. Double click the "client" name in the folder view on the sidebar
    2. Go to Signing & Capabilities
    3. Check Automatically manage signing
    4. Make sure the team is set to Sovereign Engineering Inc.
    5. Set target to Dev Client > My Mac or any other buildable target
    6. Press "Play" aka run project
    7. Click Register Device
  6. Enable system extension developer mode
  7. Setup Developer ID provisioning profile and codesigning for Prod Client build scheme
    1. Go to https://developer.apple.com/account/resources/profiles/list
      • Download "Developer ID: System Network Extension"
      • Download "Developer ID: VPN Client App"
    2. Install both provisioning profiles by double-clicking them.
    3. Ask Carl to send the Developer ID codesigning certificate and the corresponding password
    4. Double click the certificate, enter the password, and install it to your "login" keychain which you need to select in the password input screen

Building and Running

For macOS and iOS

  1. Open the main Xcode project:

    bash
    nix develop --print-build-logs --command just xcode-open
  2. Pick a build scheme using Xcode's GUI, one of:

    ℹ️ INFO: Xcode differentiates between "build schemes" and "build configurations", see Apple's docs on this for more details.

    1. Dev Client: Development Client

      General purpose for development. Uses the main UI with additional developer and pre-release features exposed.

      Uses the Debug* build configurations. Codesigned with the Apple Development xcode-managed identity.

      ⚠️ WARNING: When using this build scheme, make sure you are quitting the app via the top-right status menu bar and NOT using Xcode's "Stop" as doing so does not actually stop the dev server. This is because stopping via Xcode doesn't run the build scheme's "Run → Post-actions"

    2. Prod Client: The App with a static web bundle

      Useful for reproducing what the final shippable app will look like and be built as.

      Uses the Release* build configurations. Codesigned with the Developer ID Application: Sovereign Engineering Inc. (5G943LR562) manually-managed identity.

      The static web bundle built with the build scheme's "Build → Pre-actions".

      If you encounter trouble with this build scheme, especially with codesigning or provisioning profiles:

      1. Make sure that you've completed the relevant steps in setup
      2. See additional instructions in Confirming "Developer ID" Setup
    3. Bare Client: The App with a minimal HTML UI

      Useful for fine-grain control and debugging.

      Uses the Debug* build configurations. Codesigned with the Apple Development xcode-managed identity.

  3. Build or Run the App

    • ⌘ + B (Build), or
    • ⌘ + R (Run)

    TIP: It may initially seem like Xcode is doing nothing when you run or build, but it may just be running the build scheme's "Pre-actions", see the "Report navigator" in Xcode's top-left app menu: "View → Navigators → Reports" to track the actual status.

    TIP: If a build fails with could not find included file 'buildversion.xcconfig' in search paths, see the relevant troubleshooting entry.


    Xcode places built products in a deeply nested directory structure that it controls, with seperate folders for each build configuration. The easiest way to locate where the app is:

    1. "Run" the app
    2. Once the app's icon appears on the macOS Dock, ⌘-Click the app icon to reveal it in the finder.

TIP: It is highly recommended to read through various sections in Development Tips to better understand the various ways we've configured the Xcode build system to work with our development process.

For Android

Nix Builds

Nix builds provide an easy way to get a fully built APK. They are hermetic and reliable. However, they provide only coarse grained caching so if you are iterating during development you may prefer to use Incremental Builds.

bash
nix build '.#apks-foss'
apksigner sign --ks your-keystore.jks --ks-pass pass:hunter2 --out=obscura-signed.apk result/app-foss-release-unsigned.apk # Sign.
adb install obscura-signed.apk # Push to your device.

Instead of app-foss-release-unsigned you can also use app-foss-debug for the debug build. Note that just the Android portion is a debug build, the Rust core and UI are still release builds.

Incremental Builds

The Android app requires a special build of the Rust library and Obscura UI. These are built using Nix, while the Android app itself can be built using Android Studio for local development, or the Gradle build system to create an official build.

  1. Build the Obscura UI
    bash
    OBS_WEB_PLATFORM="android" nix develop '.#web' --print-build-logs -c just web-bundle-build
  2. Build the Rust library
    bash
    nix develop '.#android' --command bash -c 'cd rustlib && cargo ndk -t arm64-v8a build --release'
  3. Open Android Studio and point it at the android directory, or
  4. Use Gradle to build everything
    bash
    nix develop '.#android' --command bash -c 'cd android && gradle --no-daemon $GRADLE_OPTS build'

In order to iterate you can just repeat the steps. 1 and 2 are only required if you changed the UI or Rust core respectively but the final APK build must always be re-run.

Gradle Dependencies

To ensure hermetic builds we pin our Gradle dependencies. If you change the dependencies you will need to regenerate the pin file.

bin/gradle-deps-update.sh

For Windows

Install Visual Studio with the following Workloads:

  • Desktop development with C++ (for Rust)
  • WinUI application development
  • Afterwards, install HeatWave for Visual Studio (for the wix-msi project)

Install Rust.

Install just (winget install Casey.Just)

Install DotNET 10.

Install nvm-windows (winget install nvm-windows) and then run nvm install lts && nvm use lts && corepack enable.

You may also need to install Windows App SDK manually to get the client app running.

Install Powershell 7

Optionally install winapp cli: winget install Microsoft.WinAppCli

On Windows, definitely ARM64 machines, you need to add C:\Program Files\Microsoft Visual Studio\18\Community\VC\Tools\Llvm\ARM64\bin to path.

Download the signed wintun 0.14.1 DLLs.

You can use Get-FileHash -Path .\wintun-0.14.1.zip -Algorithm SHA256 to verify the hash against SHA2-256: 07c256185d6ee3652e09fa55c0b673e2624b565e02c4b9091c79ca7d2f24ef51.

Extract to windows/wintun-0.14.1 such that windows/wintun-0.14.1/bin/arm64/wintun.dll is a file.

To test the service, if you have sudo enabled (System > Advanced settings), you can run just service. Alternatively, open an admin-enabled terminal and run cargo run --bin obscura service in the rustlib dir.

To run the debug build while the client is already installed, make sure to stop the Windows service before running the service in debug mode with the debug GUI client.

The default config directory is %APPDATA%\Obscura. When testing the service, you may find it beneficial to manually add in an account number to config.json.

To clean DNS query manually from powershell, run Remove-DnsClientNrptRule -Name "{fb157da8-6578-4f53-81ea-0a9168e96c1f}"

You might need to add a source to dotnet nuget:

  1. Navigate to windows/obscura-client.
  2. Run dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org.
  3. Download the dependencies via dotnet restore.

To run the UI, you have two options

  1. Visual Studio (open obscura-client.slnx)
  2. Run just ui [arch]

Cross-Compiling

  • If on x64, install ARM64 rustup target add aarch64-pc-windows-msvc
  • If on ARM64 install x64 rustup target add x86_64-pc-windows-msvc

The Rust service links aws-lc-sys/ring, which compiles C and assembly.

Cross-compiling x64 from a ARM64 host:

  1. NASM + Ninja installed,

    powershell
    winget install NASM.NASM Ninja-build.Ninja

    Add NASM installation (%LOCALAPPDATA%\bin\NASM) to PATH environment variable.

  2. When building obscura-client.csproj for x64 on ARM64, AWS_LC_SYS_CMAKE_BUILDER=1;CMAKE_GENERATOR=Ninja is automatically set.

Cross-compiling ARM64 on a x64 host has the following requirements:

  1. Have NASM installed
  2. When building obscura-client.csproj on x64, AWS_LC_SYS_CMAKE_BUILDER=0 is automatically set, forcing aws-lc-sys's CMake-free cc builder (the CMake builder nests object paths past Windows' MAX_PATH).

Tips

To override the version (or any other properties) of a build, you can set the OBSCURA_VERSION environment variable in obscura-client/local.props and wix-msi/local.props.

xml

  
    v0.165.2
  

GUI logs are written to %LOCALAPPDATA%\Obscura\logs

When service is running as as system service, the config file is written to %SystemRoot%\System32\config\systemprofile\AppData\Local\Obscura

The WinUI 3 Gallery app is very useful at showcasing features currently available with code snippets.

Segoe Fluent Icons

When updating the .NET version, ensure windows-build.yml is updated as well.

Packaging

Inside Visual Studio,

  1. obscura-client unpackaged should be selected at the top.
  2. Select Release, x64 (or ARM64).
  3. Build the wix-msi project.

Note this requires a self signed certificates to test.

Swift unit tests

"Swift Testing" tests are placed in *Test.swift f

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rustmacosquicrustwireguard

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言